/mcpHow to point Claude Code, Cursor, or any MCP-speaking client at a graphden
instance, and what the live MCP cycle honestly does and does not verify.
The endpoint itself (JSON-RPC shape, per-branch serving, the tool
implementations) lives in resources/packages/mcp/ — this page is the
client-side setup and the workflow contract.
One route: POST /mcp (JSON-RPC 2.0, stateless streamable-HTTP).
Auth-required — the bearer is a normal graphden token, so every AI tool
call carries exactly that user’s rights (on the cloud: org scoping, RLS,
grants, effect gate; on a bare self-host: the single AUTH_TOKEN). The
mcp package is optional: absent from :package-names ⇒ /mcp 404s.
The graph reads (list-namespaces, search-fns, read-fn, the
unread-bindings of describe-fn) pass the same view-impl filter as the
editor’s GET /api/graph/entities: a fn whose composition the caller’s org
may not see (another org’s shared fn, no :view-impl grant) reads as its
signature only, and nothing it is built from rides along in read-fn.
Tools: list-namespaces, search-fns, read-fn, describe-fn,
execute-fn, create-branch, upsert-fn-defs, run-tests,
list-branches, diff-branch. Resource: graphden://ai-context (the authoring guide —
tell your agent to read it first).
Local scope (per-machine, not committed — right for worktree stacks whose ports differ per claim):
claude mcp add --transport http graphden http://localhost:<port>/mcp \
--header "Authorization: Bearer <token>"
Committed .mcp.json (only for an instance with a stable port):
{
"mcpServers": {
"graphden": {
"type": "http",
"url": "http://localhost:9002/mcp",
"headers": { "Authorization": "Bearer ${AUTH_TOKEN}" }
}
}
}
Any client speaking streamable-HTTP MCP works the same way: URL
http(s)://<host>/mcp, an Authorization: Bearer <token> header, no
session state (every call is standalone).
Reads (read-fn, describe-fn, search-fns, execute-fn,
list-namespaces) run against the branch the REQUEST rides:
X-Graphden-Branch: <name> or ?branch= — or, per call, the optional
branch tool argument, which re-dispatches that one call to the named
branch (so a static client config never needs a header). Mutations
name their branch explicitly (upsert-fn-defs takes branch) and
never fall back to main. The header form is still what curl uses:
curl -s http://localhost:<port>/mcp \
-H "Authorization: Bearer $TOKEN" \
-H "X-Graphden-Branch: ai/my-feature" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
"params":{"name":"execute-fn","arguments":{"name":"my-fn","args":{}}}}'
The intended loop for AI-assisted fn-def work on this repo:
bb wt claim <name> → bb wt up (isolated stack; the printed port).claude mcp add --transport http graphden http://localhost:<port>/mcp.create-branch ai/<feature> →
upsert-fn-defs (EDN exactly in fns.edn syntax) → execute-fn /
run-tests → read -32602s and sync errors as actionable feedback.resources/packages/**/fns.edn verbatim
(the formats are identical — that is the point of the loop).bb wt up again (the only step that runs the real
package boot-sync) → bb ci → bb wt merge.| The MCP cycle verifies | Only the real boot-sync (bb wt up) verifies |
|---|---|
| Composition wiring, arg binding, renames | Package load-order (package.edn deps) |
| Type-check of the synced bundle | Topological sort across the WHOLE package set |
| Name collisions, cycles within the bundle | :packages/ambiguous-ref across package boundaries |
Real execution semantics (same pipeline as /api/execute) |
packages.owned registration, :branch-local? seeds |
Test results (run-tests = the standard runner) |
Frontend assets, resource overrides |
A fn’s computed contract on the branch (describe-fn: free args, the start-blocking subset, effects, return type, service-eligibility, unread-bindings — bindings whose every reader is already bound closer, i.e. silent no-ops) |
— |
What a run actually walked (execute-fn with trace: true — the call tree, one row per fn invoked; a step that never appears ran nothing) |
— |
The subtree as fns.edn (read-fn — the same syntax upsert-fn-defs takes; format: "rows" for the raw rows) |
— |
Not for the MCP cycle: impls.clj edits (a new defbase needs a rebuild —
fast-check hypotheses over nREPL instead, see the graphden-repl skill),
frontend, docs, trivial constant/description edits.
Guard: upsert-fn-defs refuses fn-defs whose deterministic id is
package-owned (the platform set the boot sync restores) unless
allow-platform-overwrite is passed — build under your own namespace.
It also refuses what the editor and the API refuse on a single binding —
re-binding a slot an ancestor already valued (value-override), binding
a slot an ancestor sealed with :terminal true (terminal-seal),
appending to a list an ancestor closed (list-closed) — over the whole
bundle before a row lands (packages.sync/sync-bundle!; the same check
guards registry install / fork / import). Tutorial lesson 07.
:9002 on the dev
host) — worktree stacks exist so agents don’t fight over one graph.claude mcp add
after every bb wt up, and expect a stale config after bb wt drop.fn-defs travel as EDN TEXT inside the JSON call — only EDN keeps
:other-fn (a reference) distinguishable from "other-fn" (a string).execute-fn waits up to 10s inline and uses the shared execution
pipeline. trace: true captures the call tree and persists the run;
intermediate-value capture is not exposed by this tool. Effectful runs
also persist, and runs still pending after the inline wait return an
execution-id.