Standard Operating Procedure: MCP library

Use this when adding a server to the kit catalog, composing a host 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 (wk -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.

Cloud Agent and Automations

Hosted Cloud Agent and Cursor Automation sessions only see MCP servers connected on the Cursor dashboard. wk mcp --install rewrites local Cursor/Claude/Copilot/Antigravity files. It does not add tools to that catalog.

Loops that file or play Linear work need GitHub, Linear, PostHog, Cloudflare Observability, and SonarQube connected there. If they are missing, stop BLOCKED. Do not invent site lists, issue lists, or dashboard counts. A local profile already installed does not wake a Cloud session. Operator CLI: wk loops status / wk loops setup --write. Procedure: quality-loops.

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.
• First-party TypeScript stdio servers must --import the kit’s node_modules/tsx/dist/esm/index.mjs. Bare tsx/esm resolves from Cursor’s workspace cwd (the consumer app), not ~/.agents, so tool discovery fails.

3. Compose and install

# Preview
wk mcp default

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

# Collab extras (Notion OAuth, Slack env tokens; Linear is already on default)
wk mcp collab --install

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

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

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

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

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

# Warp Factory (OAuth; send/continue factory tasks)
wk mcp warp --install

# PostHog (OAuth; analytics, flags, errors)
wk mcp posthog --install

# SonarQube Cloud (user token + org in env)
wk mcp sonar --install

# SigNoz (mise-pinned stdio binary; local Docker UI or Cloud instance URL)
mise install                  # github:SigNoz/signoz-mcp-server from kit mise.toml
wk mcp signoz --install

# Project config
wk mcp project-example --project
wk mcp cloudflare-ops --project          # RUM / Worker diagnosis for this session
wk mcp restore --project                 # previous profile, or kit default
wk mcp cloudflare-ops --install          # RUM / Worker diagnosis (user-scope)
wk mcp default --install --host claude   # user-scope Claude Code only

The installer (curl | sh in Getting started, or ./install.sh from a checkout) runs the default profile install for every supported host. Opt into collab, ops, security, personal, devtools, cloud, cloudflare-ops, warp, posthog, sonar, and signoz explicitly.

4. Verify in the host

1. Restart Cursor, Claude Code, VS Code / Copilot, or Antigravity so MCP reloads.
2. Confirm the server shows a healthy status in that host’s MCP UI.
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 that host.

Host paths: docs/hosts.md.

5. Project handshake

For app repos, keep kit standards via AGENTS.md and optionally commit composed project MCP files (no secrets) using wk mcp <profile> --project. After a named session profile (cloudflare-ops, posthog, …), wk mcp restore --project recomposes the previous name (kit default if none). The stamp .wk-mcp-profile.stamp is gitignored and holds profile names only. Starting fragment: templates/project-mcp.json.