MCP setup

The Model Context Protocol (MCP) is how Engrym integrates with AI coding agents. Once the MCP server is wired, your agent — Claude Code, Claude Desktop, Cursor, Windsurf, Gemini CLI, Codex, or ChatGPT — automatically pulls team context, queries the Brain, logs decisions, and broadcasts intents on your behalf.

What is MCP?

MCP is a JSON-RPC protocol developed by Anthropic that lets an AI agent talk to external tools. The agent sees a list of available tools (with descriptions), picks the right one for the user's request, and invokes it. Engrym ships an MCP server (@engrym/mcp-server on npm) with tool descriptions written as agent-facing prompts — the model reads them directly and decides when to use each tool.

The server runs locally over stdio, spawned on demand via npx — no global install required.

Set up with one command

The recommended path is the one-liner from the dashboard onboarding flow (it appears when you create a project, alongside your setup token):

ENGRYM_SETUP_TOKEN=<your-token> npx @engrym/cli setup claude-code

Replace claude-code with your tool: claude-code, claude-desktop, cursor, windsurf, gemini, or codex. (ChatGPT connects differently — as a hosted remote connector; see Remote connector below.)

This single command:

Validates the token against the Engrym API and resolves your project automatically.
Writes the credential once, to ~/.engrym/config.yaml (file mode 600).
Registers the MCP server with the tool. The registration spawns npx -y @engrym/mcp-server@latest — the credential is never written into any tool's config; the server reads it from ~/.engrym/config.yaml at startup.

Pass the token via the ENGRYM_SETUP_TOKEN environment variable (preferred — it stays out of your shell history) rather than the --token flag.

What each tool target does

Tool	Mechanism
`claude-code`	Runs `claude mcp add --scope user` (requires the `claude` CLI on your `PATH`); registers in the user-scope config
`claude-desktop`	Merges into `claude_desktop_config.json`
`cursor`	Merges into `~/.cursor/mcp.json`
`windsurf`	Merges into `~/.codeium/windsurf/mcp_config.json`
`gemini`	Merges into `~/.gemini/settings.json`
`codex`	Prints a TOML `[mcp_servers.engrym]` snippet to paste into `~/.codex/config.toml`

Every registration is the same credential-free spawn directive:

{
  "mcpServers": {
    "engrym": {
      "command": "npx",
      "args": ["-y", "@engrym/mcp-server@latest"],
      "env": {}
    }
  }
}

Restart the tool after setup — most agents cache the tool list.

Windsurf

Windsurf (Codeium's editor) is a local stdio host, wired exactly like Cursor or Codex.

Fastest path — one command writes the config for you:

Run the setup command with your token:

ENGRYM_SETUP_TOKEN=<your-token> npx @engrym/cli@latest setup windsurf

Restart Windsurf so it loads the Engrym tools.

Manual path — if you'd rather edit the config by hand:

Open (or create) ~/.codeium/windsurf/mcp_config.json.

Add the Engrym server:

{
  "mcpServers": {
    "engrym": {
      "command": "npx",
      "args": ["-y", "@engrym/mcp-server@latest"]
    }
  }
}

Restart Windsurf so the Engrym tools load.

Verifying the wire

In Claude Code, claude mcp list should show engrym as connected. Then ask the agent a question about your project:

"What's our team context right now?"

If the wire is healthy, the agent invokes get_team_context against the Engrym MCP server and answers from project truth — not from training-set memory.

The tools the server exposes

The server exposes 23 tools. Descriptions ship with the server as agent-facing prompts, so agents know when to call each one without extra prompting. They group into six jobs: orient, read, coordinate, write, extract, and reconcile.

Orient — get the lay of the land

Tool	What it does
`get_project_brief`	The cold-start orientation pack for a project the agent doesn't know yet. One read returns the north-star, active constraints, active conventions, recent decisions, and current focus
`get_init_brief`	The first-run summary — what the Brain already knows AND what it doesn't, with honest counts of decisions, conflicts, and constraints, plus the decisions nobody wrote a rationale for
`get_team_context`	Returns the team's accumulated knowledge — conventions, constraints, recent decisions, active work by teammates. Agents call it at session start
`get_session_state`	Retrieves the latest persisted session state, so a session can resume where the last one left off — including across machines
`list_projects`	Discovers which Engrym projects the credential can reach, so an agent can read knowledge from a sibling project, not just the one it's connected to

Read — pull the right knowledge

Tool	What it does
`query_brain`	Search across Brain atoms by keyword, category, or scope, ordered by relevance
`get_relevant_knowledge`	Loads the conventions and constraints that govern the exact file or topic being worked on — the local rules, inherited unprompted
`get_related_atoms`	Walks the knowledge graph out from one atom — what it was derived from, what extends it, what contradicts it — so the reasoning around a decision is visible, not read in isolation
`get_atom_source`	Returns the citation for an atom — the exact source document and section it came from — before the agent relies on a claim or repeats it
`get_timeline`	A changelog over the project's knowledge: what changed since a given date, or how one decision evolved through its supersession history

Coordinate — work alongside other agents

Tool	What it does
`broadcast_intent`	Announces what the agent is about to work on, with the files it expects to touch, so other agents are aware
`release_intent`	Marks a previously broadcast intent as done
`check_conflicts`	Checks whether other team members' active intents overlap the files about to be edited
`get_active_intents`	Lists the currently active intents in the project for situational awareness
`save_session_state`	Persists session state — last task, recently touched files, unfinished work — so the next session can resume, possibly on another machine

Write — add to the Brain

Tool	What it does
`add_brain_entry`	Creates a new Brain atom — a convention, constraint, or context fragment — with metadata
`log_decision`	Records a significant architectural, design, or convention decision with its rationale and alternatives, so future sessions understand the WHY
`write_document`	Writes a plain-Markdown project document; the Brain re-derives atoms from it asynchronously. Born provisional — nothing becomes canonical until a human ratifies it in the dashboard

Extract — fill the Brain in agent mode

Tool	What it does
`pull_extraction_work`	Pulls agent-mode extraction work — the documents that need extraction plus the prompt to extract them with — so the agent runs the extraction on its own model and subscription. Gated: only when the user asks, or when the project's auto-pull consent explicitly authorizes it
`submit_extraction`	Posts one document's extraction result back as a keep/change/add/remove diff of knowledge atoms. Submissions land provisional and ratification-gated — a proposal, not a publication

Reconcile — keep the docs honest about the code

Tool	What it does
`find_contradictions`	Surfaces places where the team's knowledge disagrees with itself — a decision that violates a constraint, or two atoms asserting opposites — for a human to review. A recommender, not an actor: it flags, it never resolves
`get_reconciliation_claims`	Fetches the project's documented claims (decisions, conventions, constraints) so an agent can read the actual code locally and judge whether the code still honors each one. Engrym never sees the code
`submit_reconciliation_verdict`	Reports one verdict per claim — upheld, violated, or uncertain — with a pointer to where the agent looked. Never the code itself. A `violated` verdict routes to the human review queue

Troubleshooting

Agent doesn't see Engrym tools — restart the agent after setup; most agents cache the tool list aggressively.
setup claude-code fails — the claude-code target shells out to the claude CLI; make sure Claude Code is installed and claude is on your PATH.
Server exits at startup — the server makes one authenticated probe when it boots; if the credential in ~/.engrym/config.yaml is missing or revoked it exits with an error. Re-run setup with a fresh token from the dashboard.
--token vs environment variable — prefer ENGRYM_SETUP_TOKEN; flags end up in shell history.

Remote connector (hosted, no local install)

There is also a hosted remote MCP server at https://engrym-mcp-remote.fly.dev/mcp. It runs the same tools over Streamable HTTP and authenticates with OAuth — so you authorize once in the browser instead of writing a credential to disk, and nothing needs to be installed locally. This is the path for surfaces where npx can't run (the iPad / iPhone Claude Code apps, claude.ai/code on the web), and it works on the desktop too.

Two ways to connect:

Claude Code (project-scoped) — commit a .mcp.json at your repo root:
```
{
  "mcpServers": {
    "engrym": {
      "type": "http",
      "url": "https://engrym-mcp-remote.fly.dev/mcp"
    }
  }
}
```
On first run, Claude Code prompts you to trust the config, then walks you through the OAuth authorization. Because the config travels with the repo, every surface that clones it — including the iOS apps and the web — picks up the connector.
Claude Desktop (custom connector) — Settings → Connectors → Add custom connector → URL https://engrym-mcp-remote.fly.dev/mcp, then complete the OAuth authorization. The connector enumerates the same tools once you're authorized.

ChatGPT (custom connector) — connect over the same hosted URL, authorized in the browser. Menu labels vary by ChatGPT plan, so the wording here is deliberately generic:
1. In ChatGPT, open Settings and find your connector / MCP settings (look for Connectors, or an "add MCP server" / developer option).
2. Add a custom MCP connector and paste the URL https://engrym-mcp-remote.fly.dev/mcp.
3. Sign in and authorize Engrym when prompted. ChatGPT then enumerates the same tools.
Availability varies by ChatGPT plan. Custom / MCP connectors are offered on some paid plans, sometimes behind a beta or developer toggle. If you don't see the option, check your plan and any beta feature settings.

The remote server speaks standard MCP OAuth discovery (RFC 9728 protected-resource metadata + dynamic client registration with PKCE), so any MCP client that supports OAuth-backed HTTP servers can connect by pointing at the same URL.

When to use which: reach for the local stdio path above when you're on a machine where npx runs and you want the one-command engrym setup flow; reach for the remote connector when you want browser-based OAuth with no local install, or when you need Engrym on a surface that can't spawn a local process.

Next steps

Agent instructions — wiring the server gives your agent the tools; this writes the usage contract that tells it how to use them, into every agent config in one command.
Getting started — the five-minute on-ramp.
CLI reference — the full CLI command reference.
API reference — REST endpoints behind the tools.