--- title: "Cork MCP server: URL, setup and tools reference · Cork" description: "The Cork MCP server is at https://mcp.corkcli.com (Streamable HTTP, OAuth, no API key). How to add it to Claude Code, Codex, Cursor or any MCP client, and every tool it defines, with its parameters." canonical: "https://corkcli.com/docs/mcp-tools" last_updated: "2026-11-13" --- # Cork MCP server The Cork MCP server is the remote MCP server at `https://mcp.corkcli.com` (Streamable HTTP, OAuth sign-in, no API key) that gives any MCP client Cork's tools: briefings on the code an agent is about to touch, who else is changing it, notes anchored to code and messages between agents. These are the tools it defines, with their parameters. Where Cork's hooks run, the hooks do the protocol, and an agent calls a tool only when it adds something the briefing did not include. ## Connect ``` claude mcp add -t http cork https://mcp.corkcli.com codex mcp add cork --url https://mcp.corkcli.com codex mcp login cork gemini mcp add --transport http cork https://mcp.corkcli.com ``` Hermes: `hermes mcp add cork --url https://mcp.corkcli.com --auth oauth`. Cursor, VS Code and Copilot, Windsurf (now Devin Desktop), claude.ai and Claude Desktop, ChatGPT and any other MCP client: add a custom connector or remote server with the URL. Sign-in is OAuth 2.1 with PKCE, scope `collide`. Per tool: [Claude Code](https://corkcli.com/docs/claude-code.md), [Codex](https://corkcli.com/docs/codex.md), [Cursor](https://corkcli.com/docs/cursor.md), [Gemini CLI](https://corkcli.com/docs/gemini-cli.md). Most tools take `repo_id`, the repository id from its git remote, such as `github.com/org/repo`. A response may also carry teammates' changes since your last call (lines starting with `Δ`) and messages waiting for you. ## On the menu A member with read-only access does not see the tools that change state (`remember`, `send_agent_message`, `defer_intent`, `claim`, `report_edit`, `declare_intent`, `heartbeat` and `complete_intent`); calls are still checked on the server. ### get_briefing Start here for any coding task: the recent history of the repo (who changed what, renames to adapt to, hotspots, abandoned work and who is working right now). Where Cork's hooks are installed the same briefing already arrives in the agent's context. Pass path (and symbol) to also get the blast radius of what you are about to change. Read-only. - `repo_id` (string, required): The repository id, e.g. github.com/org/repo. - `days` (number): How far back to look, in days (default 7). - `path` (string): Optional file to also compute the blast radius for. - `symbol` (string): Optional symbol in path to narrow that blast radius. - `depth` (integer): Hops of dependents to include with path (default 3). ### get_symbol Exact facts about code without opening the file: the signature, parameters, calls, span and hash of one symbol, or of every symbol in the module when symbol is omitted, with the notes anchored to it and whether the file passed the repo's check. Read-only. - `repo_id` (string, required): The repository id, e.g. github.com/org/repo. - `path` (string, required): Repo-relative file path, e.g. src/auth.py. - `symbol` (string): Function, class or method name; omit for the whole module. ### blast_radius Before renaming, changing a signature or deleting: every symbol that depends on this one, level by level, with each dependent's file, owner and any in-flight work over it, from the live code graph. Read-only. - `repo_id` (string, required): The repository id, e.g. github.com/org/repo. - `path` (string, required): Repo-relative file path of the symbol. - `symbol` (string): The symbol whose dependents to list; omit for the whole file. - `depth` (integer): How many hops of dependents to follow, 1 to 6 (default 3). ### explain_code Why the code is the way it is: the history behind a path or symbol, oldest first. Each edit (who, when, what changed), completed intents with their rationales, reverted attempts and anchored notes, including uncommitted work. Read-only. - `repo_id` (string, required): The repository id, e.g. github.com/org/repo. - `path` (string): File to explain; with no symbol, the whole file. - `symbol` (string): Narrow the history to one symbol. ### recap What each agent did in the repo, session by session: edits, lines, tokens, model, estimated cost, rationales and top paths. Returns one entry per session and a dashboard link. Read-only. - `repo_id` (string, required): The repository id, e.g. github.com/org/repo. - `days` (number): How many days back, up to 90 (default 1). ### remember Save a durable team fact: a decision, constraint or gotcha, not code state. Anchored notes reach whoever touches that code and are marked stale when it is rewritten. kind="decision" saves a person's standing decision: it never goes stale, and each agent's first write there is held once with it. Returns the note ids. - `repo_id` (string, required): The repository id, e.g. github.com/org/repo. - `fact` (string): The note, one or two sentences. - `anchor` (string): Where it applies: path::symbol, a file, or dir/. - `tags` (string[]): Labels to find it by with recall. - `supersedes` (string): Id of a note or decision this one replaces; the old one is retired. kind="decision" with no fact withdraws that decision. - `kind` ("note" | "decision"): note (default), or decision; a decision needs an anchor. - `facts` (object[]): Several notes at once: [{fact, anchor?, tags?, kind?}]. ### recall Search the team's saved notes by text and tags, newest first; an empty query returns the most recent. Each note comes back with its anchor, confidence and whether it may be stale. Read-only. - `repo_id` (string, required): The repository id, e.g. github.com/org/repo. - `query` (string): Text to find in the note; empty returns the most recent. - `tags` (string[]): Only notes carrying all of these tags. - `limit` (integer): Maximum notes to return (default 25). ### send_agent_message Send a message to teammates' agents: to one account email, or with anchor (and no to) to whoever has an open intent on, or edited in the last day, that code or its callers. It arrives with their next tool result. to="@user" (or "@user/2", one of their agents) reaches any Cork user once they accept you as a contact. Returns the message id and who received it. - `repo_id` (string, required): The repository id, e.g. github.com/org/repo. - `message` (string, required): What you need them to do or know. - `to` (string): A teammate's account email, or @user / @user/2; omit it when anchor is given. - `anchor` (string): The code the message is about: path.py::symbol, path.py, or dir/. - `hub` (string): A hub's name or id, or a workspace channel: "#general" or its id. ### inbox_ack Mark messages from teammates' agents as handled so they stop arriving. Unacknowledged messages repeat on every response. Returns the messages still pending. - `repo_id` (string, required): The repository id, e.g. github.com/org/repo. - `ids` (string[], required): Message ids from messages_pending. ### defer_intent Leave work unfinished safely: a tripwire on paths or symbols that warns whoever next edits them. It fires once into their next tool result and briefing, and becomes a task in the team's CRM when one is connected. Returns the tripwire id and expiry. - `repo_id` (string, required): The repository id, e.g. github.com/org/repo. - `note` (string, required): What is unfinished and what the next person should do. - `paths` (string[]): Files whose next edit triggers the warning. - `symbols` (string[]): Symbol names whose next edit triggers it. - `expires_days` (number): Days until the tripwire expires (default 14). ### claim Reserve the next number in a sequence (a migration, an ADR, a release) so no other agent takes it; two agents asking at once never get the same number. The hooks already claim a numbered file's number when you create it. Returns the number, zero-padded like the files already there. - `repo_id` (string, required): The repository id, e.g. github.com/org/repo. - `sequence` (string, required): A directory such as db/migrations/, or a name such as release. - `title` (string): What the number is for; teammates see it. - `after` (integer): The highest number you already see in use in that directory, if any. ### pending_reconciliations When a response says two agents' work collides: claim the open collisions, with both sides' intents, changed lines and notes, to merge them, keeping both sides' work. After the merge passes the tests, call again with resolve. Returns the claimed reconciliations and how many stay open. - `repo_id` (string, required): The repository id, e.g. github.com/org/repo. - `resolve` (string[]): Ids of reconciliations you have merged and verified. ### setup Set up Cork on this machine, once for every repo on it. Returns install.command to run as given, in a shell at the repo root: it installs Cork's hooks for Claude Code, Codex, Cursor and Hermes, links the machine to your account, and writes nothing into the repo (it removes and stages an old per-repo .collide/ setup if there is one). - `repo_id` (string, required): The repository id, e.g. github.com/org/repo (its git origin). - `mode` (string): Ignored; kept for older callers. ### connect_agents The same install command as setup. mode "files" instead returns the protocol rules files and MCP configs to commit for tools without hooks (Windsurf, Cline, GitHub Copilot). - `repo_id` (string, required): The repository id, e.g. github.com/org/repo. - `mode` (string): Empty for the machine install; "files" for the rules files and MCP configs. ## Protocol calls Without hooks, an agent calls `get_briefing` first, then `declare_intent` before changing anything, `check_collisions` before writing and `report_edit` after. Once an account's hooks report, these leave its menu, because the hooks make them; a call by name still works. ### check_collisions The main check before writing. An empty list means no collisions. Otherwise each entry has the symbol, kind (renamed, modified, removed, added, unknown), detail, confidence (certain, likely, unconfirmed, unknown), author, freshness and matching intents. Exact path and symbol matching only. - `repo_id` (string, required): The repository id, e.g. github.com/org/repo. - `paths` (string[]): Files you are about to write. - `symbols_referenced` (string[]): Symbols your change calls or depends on. ### report_edit Submit a file you wrote. The server parses it in memory, updates your workspace tree and discards the source; returns parse confidence and your new root. draft=true reports presence only. expected_hashes makes the write compare-and-swap: if any symbol moved, the write is rejected with the current state. - `repo_id` (string, required): The repository id, e.g. github.com/org/repo. - `path` (string, required): Repo-relative path of the file you wrote. - `content` (string): The file's full new content. - `idempotency_key` (string): Any string; a retry with the same key is applied once. - `draft` (boolean): true: broadcast what is in motion without recording the edit. - `expected_hashes` (object): {symbol: hash you read, or null}: reject the write if any moved. - `why` (string): One line, at most 200 characters: why this change. ### declare_intent Register an in-flight change, preferably as typed operations (rename, add_param, remove_param, change_return, extract, move, delete, add, modify), which get conflict prediction against other live intents (COMMUTE, CONFLICT or UNKNOWN). TTL 15 minutes; extend with heartbeat. - `repo_id` (string, required): The repository id, e.g. github.com/org/repo. - `paths` (string[], required): Files the change will touch. - `symbols` (string[]): Symbols the change will touch. - `operations` (object[]): Typed operations, e.g. {op: "rename", symbol, new_name}. - `change_type` (string): Legacy prose kind of change; prefer operations. - `before` (string): The signature or name before the change. - `after` (string): The signature or name after it. - `summary` (string): One line on what you are about to do. - `idempotency_key` (string): Any string; a retry with the same key declares once. - `ref` (string): An issue or pull request this work belongs to. ### heartbeat Extend an active intent's TTL. The response carries since_your_last_call, the cross-agent events since your previous call. - `repo_id` (string, required): The repository id, e.g. github.com/org/repo. - `intent_id` (string, required): The id declare_intent returned. ### complete_intent Mark an intent completed (otherwise it expires to abandoned). The rationale is anchored to the changed symbols and returns as a blocking-level notice if anyone later declares an intent that would reverse this one. - `repo_id` (string, required): The repository id, e.g. github.com/org/repo. - `intent_id` (string, required): The id declare_intent returned. - `rationale` (string): Why this change was made and what was rejected. ### sync_agents_block Replace only the region between the cork markers in the given AGENTS.md content with the current canonical block (appended when the markers are absent). Apply the returned content yourself. - `repo_id` (string, required): The repository id, e.g. github.com/org/repo. - `file_content` (string, required): The current AGENTS.md content (empty when the file does not exist). ## Off the menu, still answered These are not listed, because the briefing, another tool or a dashboard page covers them, but a call by name still works. ### plan_work Before dispatching agents: collapse work units into the fewest independent groups and check each against what is open right now (run_now or hold). dispatch=true claims each run_now group as an intent and queues the held ones. - `repo_id` (string, required): The repository id, e.g. github.com/org/repo. - `units` (object[], required): {path, symbol, op?} each. - `depth` (integer) - `dispatch` (boolean): Claim every run_now group now and queue the held ones for release. ### simulate_merge Counterfactual dry-run: if the given workspaces (default all) landed together now, which symbols would disagree. - `repo_id` (string, required): The repository id, e.g. github.com/org/repo. - `users` (string[]) ### differential_check Does your workspace preserve the interfaces another user's code relies on, and the reverse. Returns PASS, FAIL or UNKNOWN and states what was and was not checked. - `repo_id` (string, required): The repository id, e.g. github.com/org/repo. - `other_user` (string, required) ### blind_spots Where Cork's map is unreliable: files never cleanly parsed, files serving stale state, workspaces gone quiet. - `repo_id` (string, required): The repository id, e.g. github.com/org/repo. ### graph_neighbors What a symbol or file depends on, what depends on it, and the relation on each edge (calls, inherits, uses_type, references). - `repo_id` (string, required): The repository id, e.g. github.com/org/repo. - `path` (string, required) - `symbol` (string) - `depth` (integer) ### graph_path The shortest chain of relations between two symbols, or "not connected". - `repo_id` (string, required): The repository id, e.g. github.com/org/repo. - `from_path` (string, required) - `to_path` (string, required) - `from_symbol` (string) - `to_symbol` (string) ### repo_map The repo in one response: subsystems and their hub symbols, what is being edited now, and where past attempts left scars. - `repo_id` (string, required): The repository id, e.g. github.com/org/repo. - `budget` (integer) ### list_activity Active intents, workspace roots, last-update timestamps, recent events. - `repo_id` (string, required): The repository id, e.g. github.com/org/repo. ### compliance_report From the ledger: check-before-write rate per user, intents completed vs abandoned, collisions vs blocks vs overrides. - `repo_id` (string, required): The repository id, e.g. github.com/org/repo. - `since` (number) ### graph_export Export the code graph: "graphify" (graph.json), "graphml" (Gephi, yEd) or "cypher" (Neo4j, FalkorDB). - `repo_id` (string, required): The repository id, e.g. github.com/org/repo. - `format` (string) ### graph_import Bootstrap the graph from a Graphify graph.json (its parsed object); files Cork parses itself keep their live parse. - `repo_id` (string, required): The repository id, e.g. github.com/org/repo. - `graph` (object, required) ### open_dashboard The dashboard URL for this repo's workspace, to hand the person. - `repo_id` (string, required): The repository id, e.g. github.com/org/repo. - `section` (string) - `path` (string) - `seq` (integer) - `seats` (integer) - `interval` (string) - `plan` (string) ### move_repo Move a watched repo to another workspace you belong to; new_workspace creates that workspace and moves the repo there. - `repo_id` (string, required): The repository id, e.g. github.com/org/repo. - `workspace` (string) - `new_workspace` (string) ### remove_repo Stop watching a repo in this workspace. Its history stays; nothing is deleted. - `repo_id` (string, required): The repository id, e.g. github.com/org/repo. - `workspace` (string) ### switch_workspace Without an argument, list the account's workspaces and which one this credential is bound to; with an id or name, re-bind the credential to it. Repos already established elsewhere keep routing to their home workspace. - `workspace` (string) ### install_hooks Install or refresh Cork's hooks on this machine: the same one command as setup. - `repo_id` (string, required): The repository id, e.g. github.com/org/repo. ## Questions ### What is the Cork MCP server? The Cork MCP server is Cork's remote MCP server, at `https://mcp.corkcli.com`. Any MCP client can use it to coordinate AI coding agents on one codebase: `get_briefing` hands an agent the signatures, callers and recent changes of the code it is about to touch, `check_collisions` says who else is changing it, and `remember`, `recall` and `send_agent_message` share notes and messages between agents. Cork is made by Lithometric. ### What is the Cork MCP server URL? `https://mcp.corkcli.com`, over Streamable HTTP. In Claude Code: `claude mcp add -t http cork https://mcp.corkcli.com`. In Codex: `codex mcp add cork --url https://mcp.corkcli.com`, then `codex mcp login cork`. In Cursor, VS Code, claude.ai, ChatGPT and other clients, add a custom connector or remote server with that URL. ### Does the Cork MCP server need an API key? No. Sign-in is OAuth 2.1 with PKCE, in the browser, the first time a client connects. Clients register themselves (dynamic client registration), so there is no key, header or client ID to set. ### Which clients work with the Cork MCP server? Claude Code, Codex, Cursor, Gemini CLI, Hermes, VS Code and GitHub Copilot, Windsurf (now Devin Desktop), claude.ai and Claude Desktop, ChatGPT, and any other client that takes a remote MCP server over Streamable HTTP. ### Is the Cork MCP server free? Yes, on Free: 10 agent hours a month per account, plus 30 bonus hours the first month, with unlimited repos and agents. More is $20 a month per unit of 100 agent hours, pooled across the workspace. See [pricing](https://corkcli.com/pricing.md). With no account at all, the [Cork CLI](https://corkcli.com/docs/cli.md) (`npx corkcli`) runs the same tools on your machine, free and local. ## More - [Cork CLI (the cork command)](https://corkcli.com/docs/cli.md) - [Documentation](https://corkcli.com/docs) · [auth.md](https://corkcli.com/auth.md) · [llms.txt](https://corkcli.com/llms.txt)