agentmako MCP server
✓ VerifiedProvides a local-first codebase intelligence engine that indexes repositories and builds SQLite-backed facts for AI coding agents.
Also known as drhalto/agentmako
- Stars
- 54
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.2.3
- Last commit
- Jul 26, 2026
- License
- Apache-2.0
What is agentmako MCP?
agentmako provides a local-first codebase intelligence engine that indexes repositories and builds SQLite-backed facts for AI coding agents.
Summary generated from the project's README
About agentmako MCP server
Providing codebase intelligence for AI coding agents is what agentmako does by indexing repositories and building local SQLite-backed facts. It serves developers using tools like Claude Code, Cursor, and Codex, helping them understand project structures, routes, and symbols before making edits. The system runs entirely locally, requiring only Node.js 20 or newer, and does not need a hosted service to function.
Users interact with the engine through an MCP server or a local dashboard. It offers a specialized tool surface including reef_ask for complex project questions, reef_status for tracking issues, and reef_impact to determine the blast radius of file changes. It can also ingest diagnostics from TypeScript, ESLint, Oxlint, and Biome, or integrate with Postgres and Supabase via schema snapshots. By using tools like context_packet and mako_help, agents receive deterministic context and workflow guidance instead of relying on broad grep searches.
What you can do with it
- 1Analyze project architectureAsk the agent to identify relevant routes, symbols, or database tables to understand the codebase structure.
- 2Assess change impactDetermine how modifying specific files will affect the rest of the project and identify potential convention risks.
- 3Verify diagnostic healthCheck if all linting errors and diagnostic issues are resolved before completing a task.
- 4Inspect database schemasPerform read-only inspections of Postgres or Supabase schemas and review RLS or trigger configurations.
Written from the project's README. Every use case is checked against a quote from it.
How to install agentmako MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall agentmako MCP in Claude Code
$ claude mcp add agentmako -- npx -y agentmakoInstall agentmako MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"agentmako": {
"command": "npx",
"args": [
"-y",
"agentmako"
]
}
}
}Install agentmako MCP in VS Code
.vscode/mcp.json
{
"servers": {
"agentmako": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"agentmako"
]
}
}
}Install agentmako MCP in VS Code CLI
$ code --add-mcp '{"name":"agentmako","type":"stdio","command":"npx","args":["-y","agentmako"]}'Install agentmako MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"agentmako": {
"command": "npx",
"args": [
"-y",
"agentmako"
]
}
}
}Install agentmako MCP in Codex
$ codex mcp add agentmako -- npx -y agentmakoInstall agentmako MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.agentmako] command = "npx" args = ["-y", "agentmako"]
Install agentmako MCP in Gemini CLI
$ gemini mcp add -s user agentmako npx -- -y agentmakoInstall agentmako MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"agentmako": {
"command": "npx",
"args": [
"-y",
"agentmako"
]
}
}
}Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachabledrhalto/agentmako is public and reachablegithub.com/drhalto/agentmako ↗Pass
- Package names this repository as its sourceagentmako names drhalto/agentmako as sourcenpmjs.com/package/agentmako ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for agentmakonpmjs.com/package/agentmako/v/0.2.3#provenance ↗Pass
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-07-26github.com/drhalto/agentmako ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from agentmakoPass
- No critical advisory in the package or its dependencies171 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubagentmako
agentmako is a local-first codebase intelligence engine for AI coding tools.
It gives agents like Codex, Claude Code, Cursor, and local harnesses a compact Reef-first tool surface for understanding a project before they edit it. Mako indexes your repo, builds local SQLite-backed facts, tracks diagnostics and review notes, and answers evidence-backed questions instead of making the agent orchestrate broad tool chains or rediscover everything with raw grep.
Mako is built for the first mile of coding-agent work:
What files matter? What routes, symbols, tables, diagnostics, and prior findings are relevant? What should the agent read next?
What You Get
- MCP server for coding agents:
agentmako mcp - Local dashboard:
agentmako dashboard - Primary project query:
reef_askacross code, database, findings, diagnostics, instructions, freshness, and literal checks - Queryable workflow orientation:
mako_help - Deterministic context expansion:
context_packet _hintson tool results so agents get result-specific next steps- Central MCP annotations so clients can distinguish safe reads, live reads, and local-state mutations
- Compact loop/fallback tools:
reef_status,reef_verify,reef_impact,live_text_search,lint_files, andtool_batch - Reef Engine facts and findings across indexed, working-tree, and staged state
- Reef convention extraction for auth guards, runtime boundaries, generated paths, route patterns, and schema usage
- TypeScript, ESLint, Oxlint, Biome, and staged git diagnostic ingestion
- Hot-reloaded
.mako/rulesYAML rule packs, including primitive cross-file helper-bypass rules viacanonicalHelper - Optional Postgres/Supabase schema snapshots and read-only DB inspection
- Local DB review comments for notes on tables, RLS, triggers, publications, subscriptions, and replication
- Recall, acknowledgements, and agent feedback for repeated review work
Everything important runs locally. No hosted service is required.
Install
Requires Node.js 20 or newer.
npm install -g agentmako
Confirm the CLI is available:
agentmako --version
agentmako doctor
You should see green checks for configuration and the local API service.
Prefer to build from source (e.g. to contribute)? See Develop From Source at the bottom of this file.
Happy Path Setup
1. Attach your real project
Go to the project you want Mako to understand:
cd C:/path/to/your/project
Attach and index it:
agentmako connect . --no-db
Use --no-db for the first run. It gets the code intelligence path
working before adding database scope.
2. Confirm Mako sees the project
agentmako status .
agentmako tool list
Run a real Reef query:
agentmako --json tool call . reef_ask "{\"question\":\"where should I inspect auth route state?\"}"
If that returns an evidence-backed answer, facts, findings, or next queries, the core setup is working.
reef_ask plans over code, database, durable findings, diagnostics, and exact
literal evidence. App-flow questions favor file, route, and finding evidence;
RLS/schema questions favor database facts and review comments. To inspect
project rules of thumb directly:
agentmako --json tool call . project_conventions "{}"
3. Configure your MCP client
Add this to your MCP client config:
{
"mcpServers": {
"mako-ai": {
"command": "agentmako",
"args": ["mcp"]
}
}
}
Restart the MCP client and confirm the mako-ai server starts.
In the agent, default to reef_ask. The compact starting surface is:
reef_askfor project questions across code, database, findings, diagnostics, freshness, and quoted literal checksreef_statusfor maintained issues, changed files, stale diagnostics, and watcher/schema healthreef_verifyfor the completion gate over diagnostic freshness and open loopsreef_impactfor changed-file blast radius and convention risksmako_helpfor an ordered workflow recipe with prefilled argumentslive_text_searchfor exact current-disk regex/glob inventorieslint_filesfor bounded diagnostics and.mako/rulesfindingstool_batchfor independent read-only follow-upstool_searchto discover specialized route, graph, DB, finding, refresh, or context-expansion tools only when the compact surface points at a concrete need
4. Optional: use an agent plugin
Plain MCP works anywhere, but the bundled plugins add Mako-specific skills and
include the same agentmako mcp wiring.
Prerequisites:
- Claude Code installed
- Node.js 20+ on
PATH(the plugin runsnpx -y agentmako mcp, which fetches the publishedagentmakopackage automatically — no separate global install required) - Your target project already attached with
agentmako connect
Claude Code stable path:
claude plugin validate .\mako-ai-claude-plugin
claude --plugin-dir .\mako-ai-claude-plugin
New generated plugin layouts:
claude plugin validate ./plugins/claude-code
codex marketplace add ./plugins
ln -s "$(pwd)/plugins/cursor" ~/.cursor/plugins/local/mako-ai
gemini extensions install ./plugins/gemini
Inside the agent, confirm the mako-ai MCP server is connected.
The plugin exposes these skills:
/mako-ai:mako-guide/mako-ai:mako-discovery/mako-ai:mako-trace/mako-ai:mako-neighborhoods/mako-ai:mako-graph/mako-ai:mako-database/mako-ai:mako-code-intel/mako-ai:mako-workflow
Use the plugin when you want Claude Code to load Mako-specific guidance for which tools to call and how to interpret their results.
5. Optional: launch the dashboard
From your target project:
agentmako dashboard .
This starts the local API, harness service, and web dashboard.
6. Optional: add Supabase/Postgres awareness
Mako works without a database. Add this only after code intelligence is working.
For a one-time interactive setup:
agentmako connect .
For CI or scripted setup using an environment variable:
set DATABASE_URL=postgres://...
agentmako connect . --db-env DATABASE_URL --yes
Then refresh and verify the local schema snapshot:
agentmako refresh .
agentmako verify .
Interactive mode stores database secrets in your OS keychain by default. Project config stores references, not plaintext DB URLs.
Normal Daily Loop
From the target project:
agentmako status .
agentmako dashboard .
agentmako --json tool call . context_packet "{\"query\":\"fix the broken auth callback route\"}"
For staged review checks:
agentmako git precommit . --json
For database review notes:
agentmako --json tool call . db_review_comment "{\"objectType\":\"replication\",\"objectName\":\"supabase_database_replication\",\"category\":\"review\",\"comment\":\"Check publication coverage before relying on realtime events.\",\"tags\":[\"supabase\",\"replication\"]}"
Develop From Source
If you want to hack on Mako itself, clone and build instead of installing from npm.
Prerequisites:
- Node.js 20 or newer
- Git
- Corepack (
corepack enable, included with modern Node.js)
git clone https://github.com/drhalto/agentmako.git
cd agentmako
corepack pnpm install
corepack pnpm run build
npm link ./apps/cli
npm link ./apps/cli makes the source-built CLI available as
agentmako on your PATH, replacing any global npm install. Re-run
corepack pnpm run build after pulling changes.
To go back to the published version: npm install -g agentmako.
Development Checks
corepack pnpm run typecheck
corepack pnpm run build
corepack pnpm run test:smoke:reef-tooling
corepack pnpm run test:smoke:reef-model-facing-views
Full verification:
corepack pnpm test
Repository Layout
apps/
cli/ agentmako CLI and MCP entrypoint (the published package)
web/ local dashboard
packages/
contracts/ public TypeScript contracts and tool schemas
config/ shared config helpers
logger/ shared logger
sdk/ programmatic SDK
store/ SQLite stores, migrations, and query helpers
tools/ shared tool implementations
harness-core/ local agent harness runtime
harness-tools/ action tools available to the harness
harness-contracts/ harness contracts and provider catalog
services/
api/ local API and MCP transports
engine/ Reef Engine fact/finding pipeline
harness/ local harness HTTP service
indexer/ repo and schema indexing logic
worker/ background worker
extensions/ provider and integration packages
storage/ schema migrations, models, queries
test/smoke/ smoke coverage
mako-ai-claude-plugin/ Claude Code plugin with Mako skills
More Docs
- Tool overview
- CLI docs
- Reef Engine
- Tool annotations
- Write tool convention
- Claude Code plugin
- Agent guidance to paste into CLAUDE.md / AGENTS.md
- Contributing
- Security policy
- Changelog
License
Apache-2.0. See LICENSE.
agentmako MCP questions
How do I add agentmako MCP to Claude Code?
Run claude mcp add agentmako -- npx -y agentmako in your terminal. Add --scope user to make it available in every project.
How do I add agentmako MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What does agentmako do for AI coding agents?
It provides a compact tool surface for understanding a project by indexing the repo, building local SQLite-backed facts, and answering evidence-backed questions.
Does agentmako require a hosted service?
No, everything important runs locally and no hosted service is required.
Can I use agentmako with my database?
Yes, it offers optional Postgres/Supabase schema snapshots and read-only database inspection.
How do I install agentmako?
You can install it globally via npm using the command npm install -g agentmako.