MCP library

Versioned catalog of Model Context Protocol servers. Same idea as skills/: shared definitions live here; wk mcp writes each host’s config file (docs/hosts.md).

Layout

mcps/
├── catalog.json              # Index of every server (id, purpose, secrets, phases)
├── profiles/                 # Named sets of server ids to install together
│   ├── default.json          # Everyday kit profile (user install via install.sh)
│   ├── collab.json           # Notion + Slack on top of default
│   ├── devtools.json         # Chrome DevTools + Next.js DevTools + Playwright
│   ├── cloud.json            # Cloudflare + Observability + Vercel (+ Context7)
│   ├── astro.json            # Astro Docs MCP + lean kit servers
│   ├── cloudflare-ops.json   # Cloudflare diagnosis (Code Mode + Observability, no Vercel)
│   ├── ops.json              # Sentry + Slack (+ default lean set)
│   ├── security.json         # Semgrep + GitHub
│   ├── design.json           # Figma (token)
│   ├── payments.json         # Stripe (OAuth)
│   ├── personal.json         # Bitwarden + LinkedIn + Polyglot + Obsidian (machine-local)
│   ├── lab.json              # Raspberry Pi / home-lab hosts
│   ├── warp.json             # Warp Factory (OAuth)
│   ├── posthog.json          # PostHog analytics / flags (OAuth)
│   ├── sonar.json            # SonarQube Cloud quality gates / issues (token)
│   ├── signoz.json           # SigNoz tokens / cost / traces (API key)
│   └── project-example.json  # App-repo example
├── servers/<id>/
│   ├── server.json           # Metadata + Cursor mcpServers fragment
│   └── README.md             # Auth, tools overview, when agents should use it
└── README.md                 # This file

Profiles (keep them small)

Profile	Servers	Install target
`default`	kit-knowledge, context7, github, memory, linear	`wk mcp default --install` (all hosts)
`project-example`	context7, github, next-devtools, chrome-devtools, playwright, postgres	`wk mcp project-example --project`
`collab`	default + notion, slack	When the team also uses Notion and Slack
`devtools`	chrome-devtools, next-devtools, playwright	Frontend / XFN project config
`cloud`	context7, cloudflare, cloudflare-observability, vercel	Workers / DNS / R2 / deploy work
`astro`	kit-knowledge, github, memory, astro-docs	Astro pages, islands, GitHub Pages
`cloudflare-ops`	kit-knowledge, github, memory, cloudflare, cloudflare-observability	Live RUM / Worker / DNS diagnosis and IaC remediations
`ops`	kit-knowledge, context7, github, memory, sentry, slack	Debug / incident / telemetry
`security`	context7, github, semgrep	Security audit sessions
`design`	context7, figma	UI delivery from designs
`payments`	context7, stripe	Billing adapter work
`personal`	bitwarden, linkedin, polyglot, obsidian	Your machine only (secrets / vault)
`lab`	raspberry-pi	Home-lab SSH to a Pi / SBC
`warp`	kit-knowledge, github, memory, warp-factory	Warp Factory tasks (send, continue locally, onboard)
`posthog`	kit-knowledge, github, memory, posthog	PostHog analytics, flags, errors (OAuth)
`sonar`	kit-knowledge, github, memory, sonarqube	SonarQube Cloud issues / quality gates (user token)
`signoz`	kit-knowledge, github, memory, signoz	Coding-agent tokens, cost, and OTel traces (API key)

One profile per session. Compose one profile that matches the work. Do not stack collab + devtools + ops into a single global mcp.json. Extra MCP tools compete for attention, inflate tool-schema tokens, and slow agents.

How it is wired

Scope	Path	When
Global (all projects)	Cursor, Claude, Copilot, Antigravity user files	`./install.sh` or `wk mcp default --install`
Project (one app)	`.cursor/mcp.json`, `.mcp.json`, `.vscode/mcp.json`, `.agents/mcp_config.json`	`wk mcp <profile> --project`

wk mcp default --install
wk mcp default --install --host claude
wk mcp default --project
wk mcp restore --project
wk mcp collab --install
wk mcp ops --install
wk mcp personal --install          # Bitwarden / LinkedIn / Polyglot / Obsidian
wk mcp lab --install               # Raspberry Pi over SSH
wk mcp astro --install             # Astro Docs MCP
wk mcp cloudflare-ops --install    # RUM / Worker / DNS diagnosis
wk mcp warp --install              # Warp Factory (OAuth)
wk mcp posthog --install           # PostHog analytics / flags (OAuth)
wk mcp sonar --install             # SonarQube Cloud issues / quality gates
wk mcp signoz --install            # Coding-agent tokens / cost / traces
wk mcp project-example --project

Secrets never live in this repo. Stdio servers use ${env:VAR}; Linear/Notion/Cloudflare/Sentry/Stripe/Vercel/Warp Factory/PostHog use host OAuth on first tool use. SonarQube Cloud uses SONARQUBE_TOKEN + SONARQUBE_ORG in headers. SigNoz stdio uses SIGNOZ_URL + SIGNOZ_API_KEY and a mise-pinned signoz-mcp-server.

Catalog

Id	Transport	Secrets / auth
kit-knowledge	stdio	none (reads `wk _ROOT` / `~/.agents`)
astro-docs	http	none
context7	stdio	none
github	stdio	`GITHUB_PERSONAL_ACCESS_TOKEN`
memory	stdio	none (file under `~/.agents/sync/`)
linear	http	OAuth
notion	http	OAuth
slack	stdio	`SLACK_BOT_TOKEN`, `SLACK_TEAM_ID`
postgres	stdio	`DATABASE_URL` (read-only / replica)
playwright	stdio	none
chrome-devtools	stdio	none (local Chrome)
next-devtools	stdio	none (Next.js 16+ `npm run dev`)
cloudflare	http	OAuth
cloudflare-observability	http	OAuth
sentry	http	OAuth
semgrep	stdio	none (`uvx semgrep-mcp`; optional `SEMGREP_APP_TOKEN`)
stripe	http	OAuth
figma	stdio	`FIGMA_API_KEY`
vercel	http	OAuth
linkedin	stdio	`LINKEDIN_CLIENT_ID`, `LINKEDIN_CLIENT_SECRET`
bitwarden	stdio	`BW_SESSION` (from `bw unlock --raw`)
polyglot	stdio	`POLYGLOT_TOKEN` (+ project `.polyglot-mcp.json`)
obsidian	stdio	`OBSIDIAN_API_KEY` (Local REST API plugin; Obsidian running)
raspberry-pi	stdio	`RASPBERRY_PI_HOST`, `RASPBERRY_PI_USER`, `RASPBERRY_PI_SSH_KEY`
warp-factory	http	OAuth (optional agent API key only for headless; never in repo)
posthog	http	OAuth (optional personal API key only for headless; never in repo)
sonarqube	http	`SONARQUBE_TOKEN`, `SONARQUBE_ORG` (Cloud user token; never in repo)
signoz	stdio	`SIGNOZ_URL`, `SIGNOZ_API_KEY`; binary via `mise install` (`github:SigNoz/signoz-mcp-server`)

Adding a server

Follow SOPs/mcp-library.md.

Agent guidance

What belongs where

Content	Mechanism
Role / phase behavior	Skills (`agent-*`)
Architecture invariants	Thin AGENTS.md; philosophy sections on demand
SOP / handover chunks	kit-knowledge
Cross-session glossary / SLOs	memory
Vendor API docs	context7
Linear issues / projects	linear (on `default`; OAuth on first use)
Live trackers / browsers / cloud	Phase profiles (`collab`, `devtools`, `ops`, …)

Discipline

Lifecycle agents declare preferred MCP ids in skill frontmatter (mcp:). Prefer those servers when a catalog entry’s phases / triggers match - and only if that server is in the installed profile.
Prefer the smallest useful set of servers - more tools ≠ better agent behavior.
Never load personal servers into shared project configs.
Do not use MCP to host skill bodies; skills stay progressive-disclosure via Cursor discovery.
Context budget: SOPs/context-budget.md.
Cloud Agent / Automation loops only see dashboard-connected servers. wk mcp --install is local. Missing tools → BLOCKED (quality-loops).

Markdown source