@vecto-os/mcp-server

Model Context Protocol server for Vecto — the graph-native project management platform.

Connect Claude Code, Cursor, or Claude Desktop directly to your Vecto instance. The AI can search the project graph, read documents, and create ideas, epics, stories, and issues through structured tools — not by piloting the UI.

Early release. Transport is stdio only; HTTP + SSE is planned.

Quick start

Add to ~/.claude.json (or your MCP client's equivalent):

{
  "mcpServers": {
    "vecto": {
      "command": "npx",
      "args": ["-y", "@vecto-os/mcp-server"],
      "env": {
        "VECTO_PAT": "vecto_pat_...",
        "VECTO_API_URL": "https://api.vecto.example"
      }
    }
  }
}

Restart the client. Eight tools and five resources become available immediately.

A Personal Access Token is required — generate one from your Vecto instance's user settings and treat it like a password.

What you get

Tools (8)

| Tool | Purpose | |---|---| | search_nodes | Full-text search across the project graph | | get_node | Fetch one node, optionally with full content | | resolve_qref | Turn @tenant/project#ref (qref) into a node | | create_idea | Create a new idea at the top of the funnel | | create_epic | Create an epic under a parent | | create_story | Create a story under an epic | | create_issue | Log a bug or incident | | update_node_status | Move a node through its status flow |

Resources (5)

| URI | Returns | |---|---| | vecto://projects | All projects you can access | | vecto://projects/{slug} | One project's metadata | | vecto://projects/{slug}/nodes/{ref} | One node's summary | | vecto://projects/{slug}/nodes/{ref}/content | One node's full content | | vecto://projects/{slug}/graph | The project's graph topology |

Configuration

Configuration loads from three places, in order — first match wins per source:

1. Environment variables
2. Workspace file — .vecto-project in the current directory only (no ancestor walk — see security note below)
3. User config — ~/.vecto/config.json

| Variable | Env | Workspace | User config | |---|---|---|---| | API URL | VECTO_API_URL | api_url= | api_url | | PAT | VECTO_PAT | pat= | pat | | Project slug (default) | VECTO_PROJECT_SLUG | project_slug= | project_slug |

VECTO_PAT is required — the server refuses to start without one. The project slug is optional; tools accept a project_slug argument and fall back to the workspace default when available.

Qref — qualified refs in free text

When referencing nodes in chat, issue bodies, or tool arguments, Vecto uses a qref — a qualified ref with an @ prefix:

@tenant/project           — project
@tenant/project#EPC-42    — a specific node
#EPC-42                   — relative ref (uses current tenant/project context)

The @ prefix follows the GitHub/Slack mention convention and keeps the reference unambiguous in free text. A trailing @server suffix is reserved for future federation between Vecto instances.

Today only resolve_qref parses the @tenant/project#ref form. Env/workspace configuration still takes a plain project slug (VECTO_PROJECT_SLUG=vcto); accepting the full qref form in config is on the roadmap.

Security: same-source rule for api_url + pat

api_url and pat must come from the same source (env + env, workspace + workspace, or user-config + user-config). The server refuses to start on mixed-source credentials.

Why: without this rule, a malicious .vecto-project file somewhere could force your user-config PAT to be sent to an attacker-controlled URL. Fail-closed is safer than silently-route-to-default.

Additionally, .vecto-project is only read from the exact working directory — no ancestor-directory walk. A parent-dir .vecto-project cannot hijack your config on shared filesystems (CI runners, multi-user hosts).

If api_url uses http:// (not https:// or a loopback address), the server writes a warning to stderr — your PAT would otherwise travel the network in cleartext.

Example .vecto-project

api_url=https://vecto.acme.com
pat=vecto_pat_abc123...
project_slug=website

Alternative install methods

git clone https://github.com/ITbrouwerij/vecto-os.git
cd vecto-os/packages/vecto-mcp
npm install
npm run build

Point your MCP client at the built entry:

{
  "mcpServers": {
    "vecto": {
      "command": "node",
      "args": ["/absolute/path/to/packages/vecto-mcp/dist/index.js"],
      "env": {
        "VECTO_PAT": "vecto_pat_...",
        "VECTO_API_URL": "https://api.vecto.example"
      }
    }
  }
}

git clone https://github.com/ITbrouwerij/vecto-os.git
cd vecto-os/packages/vecto-mcp
docker build -t vecto-mcp:0.1.1 .

{
  "mcpServers": {
    "vecto": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "VECTO_PAT",
        "-e", "VECTO_API_URL",
        "-e", "VECTO_PROJECT_SLUG",
        "vecto-mcp:0.1.1"
      ],
      "env": {
        "VECTO_PAT": "vecto_pat_...",
        "VECTO_API_URL": "http://host.docker.internal:8081",
        "VECTO_PROJECT_SLUG": "vcto"
      }
    }
  }
}

-i (keep stdin open) is required — -it would allocate a tty and break JSON-RPC framing. --rm ensures each client connection gets a fresh, stateless container.

Requirements

• Node.js 18 or newer
• A running Vecto instance with a valid PAT
• An MCP-aware client — Claude Code, Cursor, Claude Desktop, or any client implementing the Model Context Protocol

The client spawns the server as a subprocess and speaks JSON-RPC over stdin/stdout.

License

Copyright (c) 2026 ITbrouwerij — All Rights Reserved. See LICENSE.

No license is granted at this time. A more permissive license may be announced in a future release.