Skip to content

MCP & A2A — wire CortexBuild into your agent / IDE

In plain English

CortexBuild already renders into your AI tools (it writes the rules and agent personas that Copilot, Claude, Codex, and Cursor read). These two surfaces are the other direction: they let an agent or IDE ask CortexBuild questions through the two open standards the ecosystem has converged on — MCP (agent ↔ tool) and A2A (agent ↔ agent). Both are read-only, offline, and opt-in: they expose what CortexBuild already knows about your repo and never write code, mutate state, or send data anywhere.

Surface Standard What it answers Command
MCP server Model Context Protocol "What is this repo's conformance / drift / context gaps / corrective proposals?" + run an engineering persona as a prompt cortexbuild mcp serve
A2A Agent Card Agent2Agent "What agents and skills does CortexBuild offer?" (discovery) cortexbuild a2a card

1. MCP server — let your IDE consult CortexBuild

The MCP server exposes CortexBuild's committed .cortexbuild/ artefacts as MCP tools and resources, and its agent personas as MCP prompts. It speaks newline-delimited JSON-RPC 2.0 over stdio — the transport every MCP host (Claude Desktop, VS Code, Cursor, Codex) launches.

Install the extra

pip install -e ".[mcp]"

The [mcp] extra is an install handle only — it pulls no third-party dependency. The server binds no socket and performs no egress; it only reads files under .cortexbuild/.

Try it from the terminal first

# List the read-only tools the server exposes
cortexbuild mcp tools

# Call one directly (prints the JSON projection)
cortexbuild mcp call conformance --repo-root .

# List the agent personas exposed as MCP prompts
cortexbuild mcp prompts

# Get one persona (optionally applied to a task)
cortexbuild mcp prompt planner --task "add OAuth login"

What you get back:

Tool Projects
conformance the committed conformance maturity score + dimensions
context_gaps the project-context completeness score
drift a fresh, read-only render-drift check
proposals corrective-task feedback proposals (advisory)
remediations advisory remediation plans (previewable, reversible)
eval the latest agent-output eval score from the trend store
surface all of the above in one call

Every tool is also addressable as an MCP resource at cortexbuild://<tool> (e.g. cortexbuild://drift).

Wire it into an MCP host

The server is launched as a command. Point your host at the cortexbuild executable with the mcp serve arguments and the repo you want it to read.

Add to your MCP config (claude_desktop_config.json, or .mcp.json in your project for Claude Code):

{
  "mcpServers": {
    "cortexbuild": {
      "command": "cortexbuild",
      "args": ["mcp", "serve", "--repo-root", "/abs/path/to/your/repo"]
    }
  }
}

Add to .vscode/mcp.json:

{
  "servers": {
    "cortexbuild": {
      "type": "stdio",
      "command": "cortexbuild",
      "args": ["mcp", "serve", "--repo-root", "${workspaceFolder}"]
    }
  }
}

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "cortexbuild": {
      "command": "cortexbuild",
      "args": ["mcp", "serve", "--repo-root", "."]
    }
  }
}

Use an absolute command path in a virtualenv

Until CortexBuild is on PyPI you install it from source, so cortexbuild lives inside your virtualenv. If your MCP host doesn't share that environment's PATH, use the absolute path to the executable — e.g. /path/to/.venv/bin/cortexbuild (or ...\.venv\Scripts\cortexbuild.exe on Windows) — as the command.

Give the launched server a license token (registered users)

Operational commands are license-gated, and an MCP host launches cortexbuild mcp serve non-interactively — so it cannot answer an activation prompt. If no token is available, the server exits immediately with license required: … (it does not hang), and your MCP host shows only a generic "server failed to start". To avoid that, pass the token through the host's server environment:

{
  "mcpServers": {
    "cortexbuild": {
      "command": "cortexbuild",
      "args": ["mcp", "serve", "--repo-root", "/abs/path/to/your/repo"],
      "env": { "CORTEXBUILD_LICENSE_TOKEN": "cbk_<org>_<expiryYYYYMMDD>_<plan>" }
    }
  }
}

Alternatively run cortexbuild auth activate --key <token> once in the repo so the launched server picks up the local token. (Only version, info, and auth run without a token.)

Once connected

Your agent can now ask, in natural language, things like "use the cortexbuild conformance tool to check this repo's score" or "load the cortexbuild planner prompt and apply it to this task." The host negotiates the protocol version on initialize (CortexBuild supports MCP 2024-11-05 through 2025-11-25) and advertises exactly three capabilities — tools, resources, prompts. It never advertises sampling (server-initiated model calls), because that would be an egress path; the surface stays read-only by construction.

Require a bearer token when the server is exposed (opt-in)

By default the server is local stdio and needs no auth — the host launches it as a child process, so the OS process boundary is the trust boundary. If you bridge the stdio stream over a network (a proxy, a remote tier), turn on the opt-in bearer-token guard, aligned with the MCP spec's OAuth resource-server direction:

{
  "mcpServers": {
    "cortexbuild": {
      "command": "cortexbuild",
      "args": ["mcp", "serve", "--repo-root", "."],
      "env": {
        "CORTEXBUILD_MCP_TOKEN": "<the token the server expects>",
        "CORTEXBUILD_MCP_AUTHORIZATION": "Bearer <the token the client presents>"
      }
    }
  }
}
  • Opt-in. Setting CORTEXBUILD_MCP_TOKEN (or dropping a .cortexbuild/mcp/auth-required marker) turns the guard on; otherwise the local path is unchanged.
  • Fail-closed. With the guard on, every method — including initialize — is rejected with JSON-RPC error -32001 unauthorized unless the request carries a matching Authorization: Bearer <token>. The token is compared in constant time and is read by reference from the environment — never hardcoded or committed. If the guard is on but no expected token is configured, the server stays closed (a misconfiguration never opens it).
  • A bridging proxy injects the client's Authorization header into CORTEXBUILD_MCP_AUTHORIZATION; the stdio transport forwards it to the guard.

2. A2A Agent Card — let other agents discover CortexBuild

A2A is the agent ↔ agent standard. Its Agent Card is a discovery document that tells other agents what CortexBuild is and what it can do — its engineering agent roster (planner, critic, builder, …) and its read-only data skills (the same ones the MCP server exposes), advertised as A2A skills.

Install the extra and emit the card

pip install -e ".[a2a]"

# Print the card
cortexbuild a2a card --repo-root .

# Write the standard discovery file (.well-known/agent-card.json)
cortexbuild a2a card --write

The card is deterministic and byte-stable — re-emitting it produces an identical file. By default it advertises no remote endpoint ("url": null, "streaming": false): it is a capability advertisement, not a live A2A task server. If you front CortexBuild with an A2A endpoint of your own, pass --url https://your-endpoint and it is echoed into the card verbatim.

{
  "protocolVersion": "0.3.0",
  "name": "CortexBuild",
  "capabilities": { "streaming": false, "pushNotifications": false },
  "url": null,
  "skills": [
    { "id": "agent-planner",      "tags": ["engineering-agent"] },
    { "id": "read-conformance",   "tags": ["read-only", "mcp"] }
  ]
}

Safety & scope (read this once)

Both surfaces hold every CortexBuild invariant:

  • Read-only. No tool, resource, prompt, or card ever writes your code, mutates .cortexbuild/, or creates a second source of truth — they project the one authoritative artefact tree.
  • Offline + opt-in. The default install binds nothing and pulls no new dependency. A surface activates only when you launch it.
  • Fail-closed. An unknown method, tool, or prompt returns a well-formed JSON-RPC error — never a crash or a stack trace. A missing artefact returns a structured "not present" result, not an error.
  • No egress. Neither surface sends data anywhere. Running agents (the mutating Planner → … → PR-Reviewer workflow) and any live A2A task endpoint are a separate, explicitly-gated capability — the task/execution seam — not part of these read-only surfaces.

Next