Pair an agent

Pairing is how an assistant becomes a guest of your vault. It gets a connection token and, separately, a grant. Without a grant, tools fail closed.

Runtimes

The Hub generates a recipe per assistant. The situation package is the same; only the config file shape changes. Cursor and Hermes are validated. The others ship a recipe; we have not run them as a daily driver.

Id Runtime Status Where to paste
cursor Cursor Validated Cursor Settings → MCP (user / this machine)
claude-code Claude Code Recipe Claude Code user MCP settings
claude-desktop Claude Desktop Recipe Desktop mcpServers (on WSL, run the bridge inside WSL)
chatgpt ChatGPT Recipe MCP connector in ChatGPT settings (plan must allow MCP)
hermes Hermes Validated mcp_servers in ~/.hermes/config.yaml, then /reload-mcp
openclaw OpenClaw Recipe mcp.servers in ~/.openclaw/openclaw.json

Pasting into a single project’s .cursor/mcp.json works but is optional. Prefer user/machine settings so every window can reach the Hub. Do not commit that file — it contains a live token.

In the Hub

  1. Start the Hub (pch or make serve).
  2. Open Agents (/connections).
  3. Create a pairing link. Name it after the runtime (“Cursor”).
  4. Either:
    • Pair from the runtime with the one-time code, or
    • Generate a recipe for that assistant and copy the JSON/YAML snippet.
  5. On Agents, attach a grant:
    • read_project + the project you care about, or
    • read_active_projects for a broader read, and/or
    • always_ask_before_sending if the agent might propose outward actions.

Grant text is the plain-language summary (summary_human). Read it before confirm.

What the recipe contains

All recipes run the stdio bridge:

<python> -m pch_sdk mcp-bridge

with environment:

From a source checkout:

make bridge TOKEN=<connection-token>

or:

PCH_TOKEN=... PCH_BASE=http://127.0.0.1:8765 uv run pch-sdk mcp-bridge

The bridge health-checks GET /health and forwards MCP tools to POST /v1/mcp/tools/{name}. It does not expose MCP resources over stdio (tools only). Resources remain available over HTTP: GET /v1/mcp/resources?uri=.

Runtime rule (paste into personal guidance)

The recipe includes this rule. Assistants should follow it:

The situation package also returns capture_hints with the same idea, so capture is not only in the tool description.

Cursor, specifically

  1. make serve or pch
  2. Agents → pairing link → Cursor → copy JSON
  3. Cursor Settings → MCP → add the server (user / this machine)
  4. Reload MCP servers
  5. Grant a preset
  6. Ask a question about the granted project

Verify the tools appear: search_personal_context, get_context_contract, propose_memory, and the rest of the MCP catalog. Tests prove the published mcpServers recipe over stdio; Cursor IDE is not launched in CI.

Hermes, specifically

  1. make serve or pch
  2. Agents → pairing link → Hermes → copy YAML
  3. Add it under mcp_servers in ~/.hermes/config.yaml
  4. /reload-mcp in the Hermes session
  5. Grant a preset
  6. Ask a question about the granted project

From a checkout you can also:

hermes mcp add personal-context-hub --command <python> --env PCH_TOKEN=… PCH_BASE=http://127.0.0.1:8765 --args -m pch_sdk mcp-bridge
hermes mcp test personal-context-hub

Do not point a test HERMES_HOME at your real ~/.hermes. The validated path is the published recipe command plus MCP get_context_contract.

Pair from code (reference agent)

uv run pch-sdk demo-agent --pair <code>
# or
make demo-agent CODE=<code>

Python:

from pch_sdk import Client

c = Client("http://127.0.0.1:8765", token="")
print(c.pair("<code>"))
print(c.call("get_context_contract", purpose="continue planning the trip"))

POST /v1/connections/pair does not require the owner token — possession of the one-time code is enough. Treat the code like a password.

Revoke

Subsequent tool calls should fail with a revoked/unauthorized error. If an assistant still “remembers” facts, that is the model, not the Hub — those facts are no longer being served from the vault.

Next