MCP Server

The Archgate MCP server exposes your project’s ADRs and compliance checks to AI agents over the Model Context Protocol. Any MCP-compatible client — Claude Code, Cursor, or custom tooling — can connect to it.

Starting the server

The server uses stdio transport. Start it with:

archgate mcp

You do not typically run this command manually. Instead, configure your AI tool to launch it automatically (see below).

Configuring in Claude Code

Add the following to your project’s .mcp.json file (create it if it does not exist):

{
  "mcpServers": {
    "archgate": {
      "command": "archgate",
      "args": ["mcp"]
    }
  }
}

Claude Code reads this file on startup and connects to the Archgate MCP server automatically. You can also run archgate init (which defaults to --editor claude) to generate this configuration along with the full .archgate/ directory.

Configuring in Cursor

Run archgate init --editor cursor to generate .cursor/mcp.json with the same server configuration. See the Cursor Integration guide for details.

Available MCP tools

The server registers five tools that AI agents can call.

`check`

Run ADR compliance checks against the codebase.

Parameter	Type	Description
`adrId`	`string?`	Only check a specific ADR by ID
`staged`	`boolean?`	Only check git-staged files

Returns a JSON summary with pass/fail status, violation counts, and detailed results including file paths and line numbers.

`list_adrs`

List all ADRs in the project with metadata.

Parameter	Type	Description
`domain`	`string?`	Filter by domain (`backend`, `frontend`, `data`, `architecture`, `general`)

Returns an array of objects with id, title, domain, and rules fields for each ADR.

`review_context`

Get changed files grouped by domain with applicable ADR briefings. This is the recommended starting point for an agent beginning a task — it combines file change detection, domain grouping, and ADR summarization into a single call.

Parameter	Type	Description
`staged`	`boolean?`	When true, only include git-staged files. Default: all changed files
`runChecks`	`boolean?`	When true, run compliance checks and include results
`domain`	`string?`	Filter results to a single domain

Returns briefings containing only the Decision and Do’s/Don’ts sections of each applicable ADR, keeping the response concise.

`claude_code_session_context`

Read the current Claude Code session transcript for the project. Returns filtered entries (user and assistant messages) from the most recent session JSONL file.

Parameter	Type	Description
`maxEntries`	`number?`	Maximum relevant entries to return (default: 200, most recent)

`cursor_session_context`

Read Cursor agent session transcripts for the project. Returns filtered entries from Cursor’s agent-transcripts JSONL files.

Parameter	Type	Description
`maxEntries`	`number?`	Maximum relevant entries to return (default: 200, most recent)
`sessionId`	`string?`	Specific session UUID to read. If omitted, reads the most recent session

Available MCP resources

`adr://\{id\}`

Read the full content of an ADR by ID. Replace the id placeholder with the ADR identifier (for example, adr://ARCH-001).

Returns the complete ADR markdown including frontmatter, rationale, decision, do’s and don’ts, consequences, compliance, and references sections.

No-project behavior

If the MCP server starts in a directory without an .archgate/ directory, all tools remain available but return guidance instructing the agent to run archgate init to initialize governance. The server does not crash or refuse to start — it provides actionable feedback so the agent can bootstrap the project.

Example usage flow

A typical AI agent session using the MCP server follows this pattern:

Agent calls review_context with runChecks: false to get a condensed briefing of all ADRs that apply to the current set of changed files.
Agent reads the briefings and identifies which architectural constraints apply to its task.
Agent reads a full ADR via adr://ARCH-002 (for example) when it needs the complete rationale or implementation examples beyond the condensed briefing.
Agent writes code following the constraints from the applicable ADRs.
Agent calls check with staged: true to validate compliance. If violations are found, the response includes file paths and line numbers so the agent can fix them.
Agent iterates until check reports zero violations.