Standard Operating Procedure: MCP library

Use this when adding a server to the kit catalog, composing a Cursor config, or wiring MCPs into a project.

1. Decide scope

Profile discipline (token / attention budget)

1. One profile per session. Compose a single named profile into mcp.json. Do not merge collab + devtools + ops + personal into one global file.
2. Match skill mcp: frontmatter. If agent-xfn lists playwright, use devtools or a project profile that includes it - do not enable every catalog server “just in case.”
3. Skills ≠ MCP. Role behavior stays in skills/. MCP is for live systems, vendor docs, memory, and kit chunk retrieval (kit-knowledge).
4. Prefer a small enabled set. Extra MCP tools compete for attention and inflate tool-schema tokens. Never commit vault sessions or compose personal into shared app repos.

See SOPs/context-budget.md.

2. Add a server definition

1. Create mcps/servers/<id>/server.json with metadata and a Cursor mcp fragment:

{
  "id": "my-server",
  "name": "My Server",
  "summary": "One-line purpose.",
  "homepage": "https://example.com",
  "transport": "stdio",
  "phases": ["impl"],
  "triggers": ["keyword"],
  "requiredEnv": ["MY_API_KEY"],
  "mcp": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "some-mcp-package"],
      "env": {
        "MY_API_KEY": "${env:MY_API_KEY}"
      }
    }
  }
}

2. Add mcps/servers/<id>/README.md covering auth, when to use, and risks.
3. Register the server in mcps/catalog.json.
4. Add the id to the right profile under mcps/profiles/ (or create a new profile).

Rules

• Never commit real tokens; only ${env:NAME} / OAuth placeholders.
• mcp object keys become Cursor mcpServers keys - keep them stable and unique.
• Prefer official or well-known packages; note the homepage for audit.

3. Compose and install

# Preview
kit mcp default

# Global Cursor config (backup written if file exists)
kit mcp default --install

# Collab tools (Linear OAuth, Notion OAuth, Slack env tokens)
kit mcp collab --install

# Ops / incident (Sentry OAuth + Slack)
kit mcp ops --install

# Security audit (Semgrep)
kit mcp security -o .cursor/mcp.security.json

# Design / payments (opt-in; tokens or OAuth)
kit mcp design -o .cursor/mcp.design.json
kit mcp payments -o .cursor/mcp.payments.json

# Personal / sensitive (Bitwarden, LinkedIn, Polyglot, Obsidian) - machine only
kit mcp personal --install

# Home lab (Raspberry Pi over SSH) - machine only
kit mcp lab --install

# Project config (Next + Chrome DevTools + Playwright + read-only Postgres)
mkdir -p .cursor
kit mcp project-example -o .cursor/mcp.json
kit mcp cloud -o .cursor/mcp.cloud.json   # optional merge by hand
kit mcp cloudflare-ops --install          # RUM / Worker diagnosis

The installer (curl | sh in Getting started, or ./install.sh from a checkout) runs the default profile install only. Opt into collab, ops, security, personal, devtools, cloud, and cloudflare-ops explicitly.

4. Verify in Cursor

1. Fully restart Cursor (or reload MCP from Customize → MCP).
2. Confirm the server shows a healthy/green status.
3. Ask the agent to use a tool from that server on a real task.
4. If auth fails, confirm the env var is set in the environment that launches Cursor (not only an unrelated shell).

5. Project handshake

For app repos, keep kit standards via AGENTS.md and optionally commit a composed .cursor/mcp.json (no secrets) using templates/project-mcp.json as a starting point.