WeaveKit Docs
PracticesAgent

Connect an agent (5 minutes, local)

Connect Claude Code, Cursor, VS Code or Claude Desktop to a local engine in about five minutes.

So you ran weave dev and it printed a MCP URL. This page takes you from that URL to a working agent in a local client — Claude Code, Cursor, VS Code, Claude Desktop, or any MCP host — using the engine on http://localhost:3000.

This is the first-run / local path. For hosts talking to a deployed engine over HTTPS (teammates' laptops, corporate gateways), see the MCP host setup practice.

Prerequisites

  • The engine running locally: weave dev (defaults to http://localhost:3000, MCP at /mcp).

  • Two values, both printed by:

    weave mcp:config
    • API key — the agent credential (Authorization: Bearer …). The scaffolded project ships a static auth.source with sk-admin; weave mcp:config picks the first static key automatically.
    • on-behalf-of ref — which identity the session acts as (X-Weavekit-On-Behalf-Of). Must be a key of adapters.mcp.identities in weavekit.config.ts, or the session is rejected with 400.

Add at least one identity if your config has none, then restart weave dev:

// weavekit.config.ts
adapters: {
  mcp: {
    identities: {
      alice: { id: 'u-alice', roles: ['sales'] },   // roles must match schema.json permissions
    },
  },
},

The two required headers

HeaderValueEffect
AuthorizationBearer <apiKey>agent auth (matches auth.source) — 401 if missing/bad
X-Weavekit-On-Behalf-Of<ref>the identity the session acts as (matches mcp.identities) — 400 if unknown

tools/list then returns a per-identity, permission-filtered tool surface. See MCP for the full contract.

weave mcp:config prints the exact snippets below, filled with your project's URL, key and identity. Run weave mcp:config --host <host> for one host, or --json for machine-readable output.

1. Claude Code

claude mcp add --transport http weavekit http://localhost:3000/mcp \
  --header "Authorization: Bearer sk-admin" \
  --header "X-Weavekit-On-Behalf-Of: alice"

Check it loaded: claude mcp list (look for ✔ Connected). Inside a session, /mcp shows the server and its tool count.

2. Cursor

Create .cursor/mcp.json (project) or add to the user config:

{
  "mcpServers": {
    "weavekit": {
      "type": "http",
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer sk-admin",
        "X-Weavekit-On-Behalf-Of": "alice"
      }
    }
  }
}

Reload Cursor (or toggle the server in the MCP panel); the tools become available inline.

3. VS Code

.vscode/mcp.json — note the top-level key is servers (not mcpServers):

{
  "servers": {
    "weavekit": {
      "type": "http",
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer sk-admin",
        "X-Weavekit-On-Behalf-Of": "alice"
      }
    }
  }
}

VS Code asks you to trust the server the first time; then the tools appear in chat.

4. Claude Desktop

claude_desktop_config.json (path varies by OS; macOS: ~/Library/Application Support/Claude/):

{
  "mcpServers": {
    "weavekit": {
      "type": "http",
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer sk-admin",
        "X-Weavekit-On-Behalf-Of": "alice"
      }
    }
  }
}

Restart Claude Desktop. On a build without remote HTTP support, use the stdio bridge below instead.

5. stdio-only hosts (bridge)

Hosts that only speak stdio connect through a small local relay (mcp-remote) that forwards to the HTTP endpoint:

npx -y mcp-remote http://localhost:3000/mcp \
  --header "Authorization: Bearer sk-admin" \
  --header "X-Weavekit-On-Behalf-Of: alice"

Configure the host with command: "npx" and the arguments above.

6. Your own agent (SDK)

Any MCP client library works — @modelcontextprotocol/sdk StreamableHTTPClientTransport with the same two headers. See the SDK example.

Verify

  • In the client: the tool list should show list_objects, describe_object, and the generic search_records / get_record / create_record / update_record / delete_record tools — filtered by the identity's RBAC.
  • From the shell: run the curl snippet from weave mcp:config --host curl (or verifying a connection). A 200/201 with an Mcp-Session-Id response header is a successful handshake.

Troubleshooting

SymptomCauseFix
401missing/wrong Authorizationuse a key present in auth.source
400 on connectunknown on-behalf-of refadd the ref to adapters.mcp.identities, or sync it into the engine directory (weave sync:identity)
server connects but no toolsidentity's roles match nothing in schema.json permissionsalign roles with the object's permissions keys
works from curl, not from the clienta proxy stripped/rewrote the two headerssee the reverse proxy practice
/mcp not foundMCP disabled or mounted elsewherecheck adapters.mcp (enabled, endpoint)

Security

  • sk-admin is the scaffold placeholder — replace it with real keys before anything leaves your machine.
  • Give each human their own on-behalf-of ref; one agent key can open many sessions, each bound to a different identity (they never share a tool surface).
  • own/department row scopes need identity — a static on-behalf-of subject is enough for own (the ownership column matches the subject's id), but department (subtree) scopes require syncing the customer's directory (weave sync:identity) so the engine has the internal ids. See Identity and the user-store practice.
  • The dev endpoint binds 0.0.0.0 by default; for a shared host, front it with TLS and a proxy (Docker / reverse proxy).

On this page