@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. 65 tools and 5 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 — by category (65 total)

| Category | Examples | |---|---| | Discovery & orientation | getting_started, list_node_types, list_plan_templates, whoami | | Read | search_nodes, get_node, resolve_qref, walk_graph | | Write | create_node, update_node, delete_node | | Edges | add_edge, remove_edge | | Plan flow | create_plan_doc, get_plan_doc, request_human_input, create_annotation, answer_decision, sign_off_plan, create_plan_from_template | | Products & workspaces | create_product, list_products, get_product, update_product, delete_product, list_workspaces, get_workspace, assign_idea_to_products | | AI-assisted PM | generate_stories_from_vision, group_stories_into_epics, set_moscow, select_mvp, generate_wireframe_for_stories | | Releases | create_release, add_epic_to_release, release_signoff | | Secrets (EPC-69) | get_secret, set_secret, list_secrets, delete_secret, rotate_secret | | Builds (EPC-72) | dispatch_build, get_build_status, get_deployment, download_artifact | | Coder dispatch (EPC-72, v0.7.0) | list_coder_dispatches, claim_coder_dispatch, complete_coder_dispatch, fail_coder_dispatch — see BYOA onboarding below |

Each tool's full schema (parameters + description) is visible via tools/list in your MCP client. Call getting_started from inside the client for a guided tour.

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 |

BYOA — Coder onboarding (v0.7.0)

Vecto's Builder layer (EPC-72) lets a Vecto-Architect-colleague hand off code-generation work to an external coder agent (Claude Code CLI, Cursor, similar). The four *_coder_dispatch tools form the agent-side API for that flow.

The flow

Vecto Architect              External agent (Claude Code CLI)
─────────────────            ──────────────────────────────────
ClaudeCodeCliRuntime
.dispatch(args)
   │
   ▼
INSERT coder_dispatches      list_coder_dispatches  ◄── user runs /coder-agent
status=pending                         │
                                       ▼
                            claim_coder_dispatch(id)
                                       │ status=claimed
                                       ▼
                            [agent reads plan-DOC,
                             writes code in worktree,
                             commits with HMAC-signed msg]
                                       │
                                       ▼
                            complete_coder_dispatch(id, commitSha)
                                       │ status=completed
                                       ▼
buildService picks up
the SHA → triggers build

Recommended PAT scope set ("coder bundle")

When you create a PAT for your coder-agent (in Vecto Settings → Tokens), request the minimal set:

| Scope | What it allows | |---|---| | graph:read | get_node, search_nodes, walk_graph — read plan-DOCs + code context | | graph:write | update_node, create_node — set STORY status, log DECISIONs/ISSUEs | | coder:dispatch | The four *_coder_dispatch tools — claim / complete / fail lifecycle |

Do not request secrets:read / secrets:write — coder agents never need Vecto-managed secrets. Credentials must come from the user's local env-vars, never from MCP.

Starting the agent

In Claude Code CLI:

$ claude
> /coder-agent
[paste the dispatch payload printed by Vecto, or skip to list]

The repo includes a ready-made workflow markdown at .agents/workflows/coder-agent.md — copy it to your own repo (or ~/.claude/workflows/) to enable the slash-command. Source: coder-agent.md in vecto-os.

Full step-by-step onboarding (PAT creation, scope-set, Claude Code config, troubleshooting): see the BYOA Coder Onboarding guide in the vecto-os repo.

Sandbox rules the agent enforces

• Never writes outside the assigned worktree path.
• Never edits node_modules/, .git/, or .env* files.
• Never runs git push — local commits only; Vecto's integrator picks up the branch.
• Never skips --no-verify on the HMAC pre-commit hook.
• Fails with structured error_code (timeout / sandbox-violation / quota-exceeded / unreachable / tool-loop-stuck / other) so the Vecto cascade-engine can route to a fall-back runtime automatically.

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.8.0 .

{
  "mcpServers": {
    "vecto": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "VECTO_PAT",
        "-e", "VECTO_API_URL",
        "-e", "VECTO_PROJECT_SLUG",
        "vecto-mcp:0.8.0"
      ],
      "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.