MCP client configuration

apps/mcp-server is a standards-compliant Model Context Protocol server built on @modelcontextprotocol/sdk. It speaks MCP over stdio and proxies tool calls to the local Crosscode daemon for the current worktree.

You do not need to start the daemon yourself. On first connection, the MCP server calls ensureDaemonRunning (apps/mcp-server/src/bootstrap.ts): if no daemon is already listening for the worktree, it writes a local replica identity if one doesn't exist yet, spawns the daemon as a detached background process, and waits for it to come up before serving any tool calls. If CROSSCODE_SERVICE_URL is set in the server's env but the worktree has no logged-in Supabase session yet, bootstrap fails fast with an explicit error asking you to log in first rather than guessing at a fix. From an agent, resolve that with the headless sign-in (crosscode login --email <e> --password <p>) or a pairing code (crosscode join --pair <code>) — not the browser flow, which needs a TTY and a human. The daemon keeps running in the background after the MCP client disconnects, so it survives individual agent sessions.

The server takes no arguments; it discovers the repository from its working directory, so each client must launch it with cwd set to the worktree root.

Claude Code

Add a project- or user-scoped server entry, for example in .mcp.json at the worktree root:

{
  "mcpServers": {
    "crosscode": {
      "command": "crosscode-mcp",
      "args": []
    }
  }
}

Or register it with the CLI from the worktree root:

claude mcp add crosscode -- crosscode-mcp

Codex CLI

Add a server entry to ~/.codex/config.toml:

[mcp_servers.crosscode]
command = "crosscode-mcp"
args = []

Codex CLI spawns MCP servers with the working directory of the Codex session, so run Codex from the worktree root (or the directory it operates in) so the server can find the local daemon connection descriptor.

OpenCode

Add a server entry to opencode.json (project or global config):

{
  "mcp": {
    "crosscode": {
      "type": "local",
      "command": ["crosscode-mcp"],
      "enabled": true
    }
  }
}

Gemini CLI

Add a server entry to .gemini/settings.json (project) or ~/.gemini/settings.json (user):

{
  "mcpServers": {
    "crosscode": {
      "command": "crosscode-mcp",
      "args": []
    }
  }
}

Cursor

Add a server entry to .cursor/mcp.json at the worktree root (project-scoped) or ~/.cursor/mcp.json (available in every project):

{
  "mcpServers": {
    "crosscode": {
      "command": "crosscode-mcp",
      "args": []
    }
  }
}

Running from source

Crosscode is not published to npm yet, so every client above runs it directly from a cloned checkout of this repository with tsx, using the tsx binary installed inside that checkout (so no global install is required) and cwd set to the worktree you want Crosscode to manage:

{
  "command": "/absolute/path/to/crosscode/node_modules/.bin/tsx",
  "args": ["/absolute/path/to/crosscode/apps/mcp-server/src/main.ts"],
  "cwd": "/absolute/path/to/your/project"
}

/absolute/path/to/crosscode is wherever you cloned this repository (after pnpm install); /absolute/path/to/your/project is the Git repository you want Crosscode to watch. This is exactly what docs/install-prompt.md generates.

All configs above are transcribed from each client's own published MCP documentation and config schema (stdio server registration under an mcpServers/mcp_servers block); none of them have been launched end-to-end against a running Crosscode daemon in this environment.

Available tools

The list below is generated from apps/mcp-server/src/tool-catalog.ts — the same module the server uses to answer tools/list — via pnpm --filter @crosscode/mcp-server generate:docs. Regenerate it after changing any tool's description or input schema. See BUILD_INSTRUCTIONS.md section 13 for the capability this tool surface implements. Tool input schemas are generated from the Zod request schemas in packages/protocol, so tools/list always reflects the daemon's actual request validation.

<!-- BEGIN GENERATED TOOL CATALOG (apps/mcp-server/src/generate-tool-docs.ts) -->

• get_workspace_state — Read the local daemon's workspace status: HEAD, branch, dirty state, and pending counts. Call this first to orient before claiming tasks, checking scope, or capturing changes.
• list_tasks — List tasks known to the local daemon. Call before claim_task to see if your work is already tracked, or after claim_task to confirm it registered.
• claim_task — Create a task, optionally scoped to a set of paths, so other agents can see what you're about to work on. Call before editing; use claim_scope afterward for finer-grained path claims tied to this task.
• claim_scope — Advertise a path claim against an existing task so other agents avoid the same files. Call after claim_task and before editing — check_change_scope is how other agents (and you) read these claims back.
• publish_intent — Capture the current working-tree edits as a durable transaction tagged with a general intent. This is the default of the three capture variants (publish_intent / submit_change_summary / announce_interface_change) — use it when the change is neither a specific summary nor an interface change. Call after making edits.
• check_change_scope — Check whether a set of paths overlaps existing claims or pending remote proposals before editing. Call this before writing to files to avoid colliding with another agent's claimed scope or an in-flight proposal.
• submit_change_summary — Capture the current working-tree edits as a durable transaction tagged as a change summary, for reporting what was done. One of three capture variants (publish_intent / submit_change_summary / announce_interface_change); call after edits, in place of publish_intent when you're summarizing completed work rather than stating intent.
• list_remote_proposals — List remote operations that are proposed and awaiting local review. Call periodically to discover incoming changes that may need request_validation or a response via submit_semantic_review.
• request_handoff — Request a handoff of a proposed operation to another participant for review. Call after publish_intent, submit_change_summary, or announce_interface_change has produced an operation you want someone else to accept or decline.
• announce_interface_change — Capture the current working-tree edits as a durable transaction tagged as an interface change. One of three capture variants (publish_intent / submit_change_summary / announce_interface_change); use this instead of the others when the edit changes a public API or contract other agents depend on.
• request_validation — Run a named validation profile and return its results. Call after making edits, before requesting a handoff or creating a checkpoint, to confirm the change is sound.
• create_checkpoint — Create a Git checkpoint of the current worktree without moving HEAD. Call after edits have been validated, to durably snapshot progress without committing to a branch.
• list_pending_semantic_reviews — List semantic reviews awaiting this agent's judgment: ambiguous change bundles the daemon needs reasoned about before it can proceed. Call periodically; each entry's requestId is answered with submit_semantic_review.
• submit_semantic_review — Submit this agent's semantic review for a pending requestId: classification, confidence, affected symbols, evidence, invariants to preserve, an optional proposed resolution, and whether it requires human approval. Call only after list_pending_semantic_reviews surfaces a requestId needing judgment.
• inspect_proposal — Fetch a proposed operation and a human-readable analysis of it. Call on an operationId from list_remote_proposals before diff_proposal or accept_proposal/reject_proposal, to understand what a proposal contains.
• diff_proposal — Get the per-path diff for a proposed operation: base/local/proposed content, classification, risk, and dependents. Call after inspect_proposal and before deciding to accept_proposal or reject_proposal, especially when requiresApproval or risk looks high.
• list_proposal_artifacts — List conflict artifacts recorded for a proposed operation. Call when diff_proposal shows conflicting or unmergeable changes, to see what the daemon captured about the conflict before you accept_proposal or reject_proposal.
• accept_proposal — Accept a proposed operation, applying it locally; pass reviewApprovals when a path required semantic-review sign-off. Call after inspecting it with inspect_proposal/diff_proposal — this is the terminal counterpart to reject_proposal.
• reject_proposal — Reject a proposed operation, discarding it without applying it locally. Call after inspecting it with inspect_proposal/diff_proposal — this is the terminal counterpart to accept_proposal.
• publish_branch — Publish accepted changes to a branch by running the named validation profile and pushing/committing the result; requires confirm: true since this is not easily reversible. Call request_validation first if you want a dry look at validation independent of publishing, and pass dryRun: true here to preview without publishing.

<!-- END GENERATED TOOL CATALOG -->

Resources

The server also exposes an MCP resource, crosscode://guidance/tool-sequencing, with agent-readable guidance on how the tools above relate to each other — the same content is in apps/mcp-server/src/resources.ts. Any MCP client can read it via resources/list and resources/read to learn the intended call sequence without needing this doc.

list_pending_semantic_reviews and submit_semantic_review are how the AI semantic reviewer (BUILD_INSTRUCTIONS.md section 12) is delegated to the connected agent instead of an external AI provider: list_pending_semantic_reviews takes no arguments and returns the pending review bundles awaiting judgment (GET /v1/semantic-reviews/pending); submit_semantic_review takes a requestId plus the same fields as packages/core/src/semantic-review.ts's semanticReviewSchema (classification, confidence, affectedSymbols, evidence, invariantsToPreserve, an optional proposedResolution, and requiresHumanApproval) and forwards them to POST /v1/semantic-reviews/:requestId/submit.

View raw markdown · generated from docs/mcp-clients.md at build time, do not hand-edit this page.