MCP Servers

MCP (Model Context Protocol) servers extend what OrchestKit agents can do by connecting them to external tools and services. They're optional — every skill and agent works without them, but MCPs add capabilities that can't be replicated with built-in tools alone.

Available MCPs

OrchestKit supports 10 MCP servers across three tiers:

Bundled (zero config)

These ship in .mcp.json and work immediately — no API keys, no setup.

API Key Required

Pre-configured in .mcp.json but need an API key to activate.

User-Installable

Not in .mcp.json — you add these per-project when needed. Agents that reference them degrade gracefully when they're absent.

Recommended by Project Type

Not sure which MCPs to enable? Match your project:

Which Agents Use Which MCPs

OrchestKit scopes MCP access per agent to keep context windows lean.

Multi-MCP Agents

Single-MCP Specialists

context7 Library Docs (18 agents)

These agents use context7 for up-to-date library documentation:

backend-system-architect, database-engineer, test-generator, workflow-architect, infrastructure-architect, event-driven-architect, data-pipeline-engineer, python-performance-engineer, llm-integrator, ci-cd-engineer, eval-runner, release-engineer, deployment-manager, git-operations-engineer, frontend-performance-engineer, accessibility-specialist, multimodal-specialist, code-quality-reviewer

No MCP Access

These agents intentionally have mcpServers: [] — they work with built-in tools only:

security-auditor, security-layer-auditor, system-design-reviewer, genui-architect, emulate-engineer, demo-producer

Setup Instructions

Bundled MCPs (zero config)

context7, memory, sequential-thinking, and ork-elicit work immediately — no API keys, no setup. They're defined in .mcp.json and start automatically.

Tavily (web research)

# Option A: 1Password (recommended — no key in config files)
# .mcp.json already uses: sh -c "TAVILY_API_KEY=$(op read '...') exec npx tavily-mcp@latest"
# Just store your key: op item create --category "API Credential" --title "Tavily API Key" "API Key=tvly-..."

# Option B: Environment variable
# Replace the .mcp.json tavily entry with:
# "command": "npx", "args": ["-y", "tavily-mcp@latest"]
# Then add to ~/.zshrc: export TAVILY_API_KEY=<your-key>

# Option C: Remote MCP (no local process)
# In .mcp.json: "type": "url", "url": "https://mcp.tavily.com/mcp/?tavilyApiKey=<YOUR_KEY>"

Free tier: 1,000 credits/month at app.tavily.com.

21st.dev Magic (component registry)

# .mcp.json already uses: sh -c "API_KEY=$(op read '...') exec npx @21st-dev/magic@latest"
# Store your key: op item create --category "API Credential" --title "21st.dev Magic MCP" "credential=<key>"

# Alternative: replace .mcp.json entry with env var approach
# "command": "npx", "args": ["-y", "@21st-dev/magic@latest"]
# Then add to ~/.zshrc: export API_KEY=<your-21st-dev-key>

Free tier available at 21st.dev.

Stitch (design extraction)

claude mcp add stitch --transport http https://stitch.googleapis.com/mcp \
  --header "X-Goog-Api-Key: <YOUR-KEY>" -s user

Get your API key from stitch.withgoogle.com/settings.

Storybook MCP (component discovery + testing)

Requires Storybook 10.3+ with Vite builder:

# Install the addon
npx storybook add @storybook/addon-mcp

# Enable docs toolset in .storybook/main.ts
# experimentalComponentsManifest: true

# Register with Claude Code
npx mcp-add --type http --url "http://localhost:6006/mcp" --scope project

Storybook must be running for dev + testing tools. The docs toolset can be published remotely via Chromatic.

Agentation (UI feedback)

Pre-configured in .mcp.json but disabled by default. To enable:

"agentation": {
  "command": "npx",
  "args": ["-y", "agentation-mcp", "server"],
  "disabled": false
}

NotebookLM (RAG + research)

uv tool install notebooklm-mcp-cli
nlm login
nlm setup add claude-code

How MCP Scoping Works

Each agent declares which MCPs it can access in its frontmatter:

---
name: frontend-ui-developer
mcpServers: [context7, 21st-dev-magic, storybook-mcp]
---

• mcpServers omitted — agent inherits ALL MCP tools from parent
• mcpServers: [tavily] — agent ONLY sees tavily tools
• mcpServers: [] — agent sees NO MCP tools

This prevents Sonnet/Haiku subagents (128K context) from being overwhelmed by tool definitions they don't need.

Token Overhead

Each MCP adds tool definitions to the context window:

When total MCP tokens exceed 10% of context, Claude Code automatically activates MCPSearch — deferring schema loading and discovering tools on demand (~85% reduction).

Graceful Degradation

Every skill works without MCPs — they just lose specific capabilities:

Disabling an MCP

Set "disabled": true in .mcp.json:

"sequential-thinking": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"],
  "disabled": true
}

Background Agent Limitation

MCP tools are not available in background subagents (run_in_background: true). This is a Claude Code platform limitation. If an agent needs MCP tools, run it in the foreground.

Next Steps

• The 3 Building Blocks — Understand agents that consume MCPs
• Configuration — Environment variables and hook settings
• Plugin Architecture — How everything loads on-demand