λx.xDocs
← app
Docs›MCP Integration›Claude Code

Claude Code + Vinculum

One command to connect. Claude Code has first-class MCP support — add Vinculum and you'll have the full tool surface in every Claude Code session.

Fastest path

If you just want to get going: run the claude mcp addcommand below and you're done. There's no API key to copy — Vinculum authenticates over OAuth, so the first tool call opens your browser to authorize.

Step 1 — Add the MCP server

Run this in your terminal, from inside your project directory:

bash
claude mcp add --transport http vinculum https://vinculum.run/mcp

The --transport http flag is required for a remote server — without it Claude Code treats the URL as a local stdio command and the connection fails. By default this writes a .mcp.json to the current project. Add --scope user to make Vinculum available in every project instead:

bash
claude mcp add --transport http --scope user vinculum https://vinculum.run/mcp

No API key — OAuth instead

Vinculum doesn't use a static API key. The first time a session calls a Vinculum tool, Claude Code runs the standard MCP OAuth flow: your browser opens, you sign in to vinculum.run, and the token is stored and refreshed for you. Nothing to paste.

Step 2 — Verify the connection

Start a Claude Code session and ask Claude to call get_briefing:

text
> call get_briefing with project="your-project-name"

# Should return a summary of your project state.
# If you get "tool not found", the MCP server isn't connected.

If it fails, check the MCP server list:

bash
claude mcp list

Manual .mcp.json setup

If you prefer to edit the config directly, add this to a .mcp.json at your project root:

json
{
  "mcpServers": {
    "vinculum": {
      "type": "http",
      "url": "https://vinculum.run/mcp"
    }
  }
}

Or let Vinculum write it for you — this drops both .mcp.json and a .claude/settings.local.json (which pre-approves the Vinculum tools so you skip per-call permission prompts):

bash
uvx vinculum-run config --client=claude-code --write -y

Self-hosted MCP URL

If you're running Vinculum locally or self-hosted, replace the URL with your instance's — same --transport http, still no API key:

bash
claude mcp add --transport http vinculum http://localhost:31415/mcp

Troubleshooting

Tool not found

Make sure Claude Code was restarted after adding the MCP server, and that you passed --transport http. The MCP server list is loaded at startup.

Authentication error

Re-run the OAuth flow — in Claude Code, remove and re-add the server (claude mcp remove vinculum then the add command above), which forces a fresh browser authorization. Confirm the server itself is reachable:

bash
curl https://vinculum.run/healthz
# → {"ok": true, "service": "vinculum"}