MCP integration

A single MCP server exposes 21 tools — code (L0/L0.5), knowledge (L1.5–L3), domain (L2.5), and the global second-brain (L4–L5) — over stdio. Drop into any MCP-aware agent with a few lines of config.

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "codegps": {
      "command": "codegps",
      "args": ["serve", ".", "--mcp"]
    }
  }
}

Replace "." with an absolute project path if you want the server to operate on a fixed project regardless of where Cursor is invoked.

Claude Code

Add to ~/.claude/claude_desktop_config.json (macOS path may vary):

{
  "mcpServers": {
    "codegps": {
      "command": "codegps",
      "args": ["serve", "--mcp"]
    }
  }
}

Codex CLI / other

Any MCP-compatible client that supports the stdio transport works the same way. The command is codegps serve [path] --mcp; no flags beyond --mcp.

Tool catalogue

Code (L0)

Tool	Purpose	Key args
`codegps_search`	Symbol search across code by name + kind.	`query, kind?, limit?`
`codegps_node`	One symbol's details — signature, docstring, location.	`name`
`codegps_sync`	Trigger code re-index.	`full?`
`codegps_analyze`	Code-grounded analysis: per-file LLM summaries + architectural layers + tags (the hybrid L0 → semantic pass).	`full?`

Knowledge (L1.5–L3)

Tool	Purpose	Key args
`codegps_context`	Primary tool. Builds context for a topic — facts + related code in one call.	`task, limit?`
`codegps_recall`	Semantic + FTS query across conversations and facts; filterable by scope and grounding.	`query, kinds?, scope?, includeEnrichment?, limit?`
`codegps_decisions`	List decisions / constraints / patterns for a topic or file.	`topic?, file?, limit?`
`codegps_business_logic`	List business rules / invariants / entities.	`topic?, file?, limit?`
`codegps_concepts`	List or inspect L3 concepts. Pass a conceptId for members + summary.	`conceptId?, domain?, limit?`
`codegps_explain`	Structured systematic-thinking view of a concept (problem / constraints / options / decision / consequences).	`conceptId`
`codegps_triage_audit`	Inspect kept vs dropped windows with rationale.	`droppedOnly?, limit?`
`codegps_verify`	Run Verifier sweep on demand.	`pruneBelow?`
`codegps_ingest`	Trigger incremental ingest + agent pipeline.	`runTriage?, runExtract?`
`codegps_status`	Counts per layer.	—

Domain (L2.5)

Tool	Purpose	Key args
`codegps_domain_model`	The business-domain graph — entities + evidence-grounded relationships, each showing its grounding.	`entity?, limit?`
`codegps_gaps`	Open questions / knowledge gaps; names the gap and cites the evidence, never fabricates the answer.	`limit?`
`codegps_enrich`	Run the enrichment pass — skills, entities/relationships, industry, gaps.	`noAgent?`

Second brain (L4–L5)

Tool	Purpose	Key args
`codegps_link`	Cross-project — where else this concept appears, with relation kind and score.	`conceptId`
`codegps_skills`	Global skill graph — technical + industry skills aggregated across projects, weighted by evidence.	`scope?, cross?, limit?`
`codegps_profile`	Big-picture knowledge profile — industries, top technical skills, evidence mix. Pass `prose` for ProfileWriter-generated portfolio markdown.	`prose?`
`codegps_learn`	Learning targets — industry-standard knowledge not yet grounded in your work.	`limit?`

Usage patterns

Carrying decisions forward

When starting work on a new feature, prompt the agent to recall prior decisions before writing code:

"Before designing the payment retry flow, call codegps_decisions with topic 'retry' and tell me what we've already decided. Then call codegps_business_logic for 'payment' to surface invariants."

Onboarding a teammate

codegps_concepts with no arguments lists the top concepts in a project ranked by member count. codegps_explain conceptId expands one into a structured brief.

Auditing what the system kept

If a decision you remember discussing didn't surface, run codegps_triage_audit droppedOnly:true to see what got filtered and why. The rationale string captures the Triage Agent's reasoning; if the filter was wrong, retune triage (bump prompt version or swap model).

Transport details

Stdio only. The server logs to stderr (not visible to the MCP client) and speaks JSON-RPC 2.0 on stdout. No network sockets are opened.

Verify the server independently:

printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0"}}}\n{"jsonrpc":"2.0","id":2,"method":"tools/list"}\n' \
  | codegps serve . --mcp