DOCUMENTATION

The Handbook

Every MCP. Every env var. Every command.

Contents

§1 Overview
§2 The 10 MCPs
§3 Compatibility Matrix
§4 CLI Commands
§5 Manifest Schema
§6 Secret Model

§1 Overview

Agent_mcp is the context layer of a three-repo system:

Agent_skills — methodology: how the agent thinks (16 skills)
Agent_hook — enforcement: what must happen (9 hooks)
Agent_mcp — context: what the agent can touch (10 MCPs)

§2 The 10 MCPs

github

P0 GITHUB_TOKEN npx · node

Issues, PRs, code search, CI failures, workflow inspection. The default "agent-touches-github" MCP. Use whenever review, hunt, write-PR, debug-CI is the goal.

npx -y @modelcontextprotocol/server-github

filesystem

P0npx · node

Controlled file IO scoped to an allowlist. Survives even when CLIs have their own file tools — bounded access is the point.

npx -y @modelcontextprotocol/server-filesystem $HOME/project

context7

P0npx · node

Pulls up-to-date library docs (React, Next.js, Supabase, Stripe, FastAPI, cloud SDKs) so the agent stops citing stale APIs. Use phrase: use context7.

npx -y @upstash/context7-mcp@latest

playwright

P0npx · node

Real browser: navigate, click, fill, screenshot, read DOM. Pairs with frontend-design skill — generate UI, then verify it actually renders.

npx -y @playwright/mcp@latest

sequential-thinking

P0npx · node

Structured multi-step thinking layer. Use for complex refactors, phased migrations, architecture design, incident debugging.

npx -y @modelcontextprotocol/server-sequential-thinking

git

P0uvx

Local repo history: blame, log, diff, commit metadata. Complements GitHub MCP (which is remote-only).

uvx mcp-server-git

postgres

P1POSTGRES_CONNECTION_STRINGnpx · node

Read schema, run queries, sanity-check migrations. Strongly recommended: point at staging/dev DB with read-only role.

npx -y @modelcontextprotocol/server-postgres $POSTGRES_CONNECTION_STRING

sentry

P1SENTRY_AUTH_TOKENnpx · node

Production exceptions → code fix in one step. Shortens the cycle that usually breaks teams.

npx -y @sentry/mcp-server

figma

P1FIGMA_API_TOKENnpx · node

Read design tokens, components, text content. Stops the agent from guessing layouts from blurry screenshots.

npx -y @figma/mcp-server

linear

P1LINEAR_API_KEYnpx · node

Read tickets, write status, surface assigned work. Connects "ticket → plan → completed" in one tool.

npx -y @linear/mcp-server

§3 Compatibility Matrix

All 10 MCPs work on all 4 clients natively (MCP is a standard protocol — every modern CLI speaks it). What differs is how the config gets written:

Client	Config file	Anchor
opencode	`~/.config/opencode/opencode.json` → `mcp.<name>`	`_managed_by` JSON field
codex	`~/.codex/config.toml` → `[mcp_servers.<name>]`	`~/.codex/.agent-mcp-managed.json`
cursor	`~/.cursor/mcp.json` → `mcpServers.<name>`	`_managed_by` JSON field
kimi	via `kimi mcp add` CLI	`~/.kimi/.agent-mcp-managed.json`

§4 CLI Commands

Command	Does
`agent-mcp list`	Tabular view of all 10 MCPs × 4 client install states.
`agent-mcp install <name> --client all\|opencode\|codex\|cursor\|kimi`	Backup, write config, anchor.
`agent-mcp uninstall <name> --client all\|...`	Remove by anchor. Refuse non-managed entries.
`agent-mcp doctor`	Schema validation, binary check, env satisfaction, anchor consistency.
`agent-mcp show <name>`	Print manifest as JSON.

§5 Manifest Schema

kind: mcp                         # required
name: github                      # required: kebab-case
version: 0.1.0                    # required: semver
description: |                    # required: >= 20 chars
  GitHub MCP server providing repo, issue, PR, code search, CI access.
  Use whenever working with github.com — reviewing PRs, hunting issues...
domain: ops                       # required
priority: P0                      # required: P0|P1|P2

compatibility:                    # required: all 4 clients
  opencode: native
  codex: native
  cursor: native
  kimi: native

source:
  type: npm                       # local | external | git | npm | pypi
  package: "@modelcontextprotocol/server-github"

mcp_command:                      # required when kind=mcp
  - npx
  - "-y"
  - "@modelcontextprotocol/server-github"

requires:
  binaries: [npx, node]
  env: [GITHUB_TOKEN]             # secret env names, never values

triggers: [github, pull request, issue, CI failure]

§6 Secret Model

Tokens never live in any file managed by agent-mcp. The flow is:

You export the token in your shell: export GITHUB_TOKEN=ghp_....
manifest declares the env name: requires.env: [GITHUB_TOKEN].
Adapter writes ${GITHUB_TOKEN} (a literal interpolation, not the value) into client config.
At runtime, the client passes the env to the MCP child process, which sees the actual token.

Schema rejects literal token patterns at load time:

# From agent/lib/manifest.py
TOKEN_LITERAL_RE = re.compile(
    r"(ghp_|gho_|sk-[a-zA-Z0-9]{10,}|AIza[0-9A-Za-z\-_]{20,})"
)
# Any manifest containing this pattern is refused.