How to add an MCP server to Claude Code

Prerequisites

Node.js 20 or newer (node -v)
Claude Code installed and signed in
agentmako on PATH — install globally below

// install & attach

$ npm install -g agentmako
$ cd /path/to/your/project
$ agentmako connect . --no-db
$ agentmako doctor

You should see green checks for config, the local API service, and indexing.

Wire MCP

Add the Mako MCP server to Claude Code. Easiest is the CLI:

// from your project root

$ claude mcp add mako-ai agentmako mcp

Or paste this into your Claude Code MCP config manually:

// json

{
  "mcpServers": {
    "mako-ai": {
      "command": "agentmako",
      "args": ["mcp"]
    }
  }
}

Where this lives User-scoped settings (~/.claude.json on macOS/Linux, %USERPROFILE%\.claude.json on Windows), or .mcp.json at the project root for project-scoped servers. Use claude mcp list to confirm.

Verify in Claude Code

Restart Claude Code, then in the session run:

// inside Claude Code

/mcp

You should see mako-ai listed as connected. You can also expand it to see registered tools — context_packet, reef_scout, repo_map, cross_search, and friends.

Optional: install the plugin

The bundled plugin adds Mako-specific Claude skills and ships its own .mcp.json, so you can skip the manual MCP step if you go this route.

// from the agentmako repo root

$ claude plugin validate ./mako-ai-claude-plugin
$ claude --plugin-dir ./mako-ai-claude-plugin

Inside Claude Code these skills become available:

/mako-ai:mako-guide — entry point and tool selection
/mako-ai:mako-discovery — find files, symbols, routes
/mako-ai:mako-trace — call graphs and references
/mako-ai:mako-neighborhoods — related code clusters
/mako-ai:mako-graph — dependencies and imports
/mako-ai:mako-database — Postgres / Supabase schema
/mako-ai:mako-code-intel — diagnostics & ESLint/Biome state
/mako-ai:mako-workflow — multi-step playbooks

First task

Inside Claude Code, ask the agent something concrete and let it use Mako. Try:

// prompt

Use the mako-ai context_packet tool first.
Task: "figure out how the auth callback works in this repo".
Show me what context_packet returned before reading any files.

You should see Claude call context_packet, get back a typed packet (target file, routes, touched symbols, findings, "read next"), and then proceed with that as a starting point instead of grep.

Tell Claude when to use Mako

Without guidance, Claude will default to its built-in tools. Drop the contents of AGENTS.md into your project's CLAUDE.md so the rules ride with the repo.

Why this matters The MCP tools are only as useful as the agent's choice to call them. Telling Claude in CLAUDE.md "before grepping, call context_packet" is the difference between a helpful tool and an ignored one.

Troubleshooting

mako-ai shows as failed in /mcp

Run agentmako doctor in your shell. If agentmako is not on PATH, reinstall: npm install -g agentmako and restart Claude Code so it picks up the updated PATH.

Tools list is empty

You probably haven't attached a project. From the project directory: agentmako connect . --no-db then restart Claude Code.

It works but Claude isn't using it

See section 06. Without explicit instructions in CLAUDE.md, Claude will reach for grep first. Tell it otherwise.

Database tools missing

Database awareness is opt-in. Run agentmako connect . (interactive) and provide a DATABASE_URL, or use --db-env DATABASE_URL --yes in CI.

Mako, meet Claude Code.