Agent Lifecycle Kit

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.

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

1. Decide scope

| Need | Put it in | |------|-----------| | Useful across most projects | mcps/profiles/default.json (+ global install) | | Kit SOP / philosophy / handover chunks | kit-knowledge on default (already) | | Linear / Notion / Slack | mcps/profiles/collab.json | | Chrome / Next / Playwright | mcps/profiles/devtools.json or project-example | | Cloudflare / Vercel | mcps/profiles/cloud.json | | Cloudflare RUM / Worker / DNS diagnosis | mcps/profiles/cloudflare-ops.json | | Sentry / Slack ops | mcps/profiles/ops.json | | Semgrep security scans | mcps/profiles/security.json | | Figma design context | mcps/profiles/design.json | | Stripe payments | mcps/profiles/payments.json | | Bitwarden / LinkedIn / Polyglot / Obsidian | mcps/profiles/personal.json (**machine-local only**) | | Raspberry Pi / home lab SSH | mcps/profiles/lab.json (**machine-local only**) | | App-specific DB + frontend stack | project-example or a custom project .cursor/mcp.json | | Personal-only experiment | Local ~/.cursor/mcp.json override (do not commit secrets) |

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 -fsSL https://raw.githubusercontent.com/mzworthington/agent-lifecycle-kit/main/install.sh | sh, 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.