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 command from the dashboard onboarding flow (it appears when you create a project, alongside your setup token). Run it in your repo folder, the folder where your .git lives:

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

Replace claude-code with your tool: claude-code, cursor, codex, gemini, windsurf, or claude-desktop. (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.
Writes Engrym's files into the folder you ran it in: the instructions block in the agent's instruction file, ENGRYM.md, and the engrym-extract command your agent runs to extract your documents. claude-desktop has no project folder, so for it the command stops after step 3.

Step 4 writes freely to a file that is missing, empty, or already Engrym's. If a file already has writing in it that Engrym did not put there, the command lists those files and asks once before it changes them; in the instruction file, your own text outside the Engrym block stays as it is. Pass --yes to answer yes ahead of time. With no terminal to ask in (a script or CI), it skips those files, prints one line for each naming --yes, and exits 0. See Agent instructions for what the files say.

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

What each tool target does

Tool	MCP registration	Files written in your repo folder
`claude-code`	Runs `claude mcp add --scope user` (requires the `claude` CLI on your `PATH`); registers in the user-scope config	`CLAUDE.md` (the block), `ENGRYM.md`, `.claude/commands/engrym-extract.md`
`cursor`	Merges into `~/.cursor/mcp.json`	`.cursor/rules/engrym.md` (the block), `ENGRYM.md`, `.cursor/skills/engrym-extract/SKILL.md`
`codex`	Runs `codex mcp add` when the `codex` CLI is on your `PATH`; otherwise merges an `[mcp_servers.engrym]` table into `~/.codex/config.toml`	`AGENTS.md` (the block), `ENGRYM.md`, `.agents/skills/engrym-extract/SKILL.md` and its `agents/openai.yaml` beside it
`gemini`	Merges into `~/.gemini/settings.json`	`GEMINI.md` (the block), `ENGRYM.md`, `.gemini/commands/engrym-extract.toml`
`windsurf`	Merges into `~/.codeium/windsurf/mcp_config.json`	`AGENTS.md` (the block), `ENGRYM.md`, `.windsurf/workflows/engrym-extract.md`
`claude-desktop`	Merges into `claude_desktop_config.json`	None

Codex and Windsurf both read AGENTS.md, so a repo set up for both carries one Engrym block in it. If you set up Cursor in a repo where Engrym's Codex skill is already in place, the command does not add a second copy, because Cursor loads skills from the Codex folder too.

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, set up exactly like Cursor or Codex.

Fastest path. One command, run in your repo folder:

Run the setup command with your token:
```
ENGRYM_SETUP_TOKEN=<your-token> npx @engrym/cli@latest setup windsurf
```
It registers the server in ~/.codeium/windsurf/mcp_config.json, adds the Engrym block to AGENTS.md (which Windsurf reads as an always-on rule), and writes ENGRYM.md and the /engrym-extract workflow.
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.

This connects the server only. To give Windsurf the instructions too, paste the block from Agent instructions into AGENTS.md at your repo root.

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 conventions, constraints, recent decisions, and the work teammates have in progress. 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 connections 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.
Skipped <file>: it has content that Engrym did not write: setup ran with no terminal to ask in, so it left that file alone. Run it again in a terminal to answer the question, or add --yes to write the file without asking.
Hosted connector stops working after an idle or long session: the session's credential reached the end of its life while the connector sat unused. Engrym renews it server-side on the next tool call, so ask again instead of reconnecting; removing and re-adding the connector doesn't make it happen sooner. If calls keep failing, it isn't an idle timeout: check that your Engrym login still has access to the project.

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: the server gives your agent the tools; the instructions block that setup writes tells it how to use them.
Getting started: the five-minute on-ramp.
CLI reference: the full CLI command reference.
API reference: REST endpoints behind the tools.