mcp-gateway-patterns
MCP Gateway design patterns for Agent Gateway, Subprocess, and Daemon isolation. Use when designing MCP integrations.
When & Why to Use This Skill
This Claude skill provides a comprehensive framework for optimizing Model Context Protocol (MCP) integrations through three distinct isolation strategies: Daemon (SSE), Agent Gateway, and Subprocess. It is designed to help developers minimize context token overhead, reduce startup latency, and manage state sharing effectively when building complex AI agent workflows and tool-heavy integrations.
Use Cases
- Case 1: Optimizing token usage for MCP servers with high tool counts (e.g., Playwright or Serena) to prevent context window exhaustion and reduce costs.
- Case 2: Designing low-latency agent architectures by implementing the Daemon (SSE) pattern for persistent, fast-starting tool connections.
- Case 3: Implementing secure tool isolation in restricted or serverless environments, such as AWS Lambda or Cloud Functions, using the Agent Gateway pattern.
- Case 4: Troubleshooting MCP tool visibility, registration errors, and naming convention conflicts during local development or project-specific configurations.
- Case 5: Establishing a standardized 2-layer protocol (Intent and Action) to maintain consistency across different MCP integrations and improve agent reliability.
| name | mcp-gateway-patterns |
|---|---|
| description | MCP Gateway design patterns for Agent Gateway, Subprocess, and Daemon isolation. Use when designing MCP integrations. |
| allowed-tools | ["Read", "Write", "Bash", "Grep", "Glob"] |
MCP Gateway Patterns
Heavy MCP servers consume context tokens. Three isolation strategies exist.
Critical Knowledge
MCP Registration Methods
| Method | File Location | Correct? |
|---|---|---|
claude mcp add --scope user |
~/.claude.json |
✅ |
claude mcp add --scope project |
.mcp.json |
✅ |
Manual ~/.claude/mcp_servers.json |
Legacy file | ❌ NOT READ |
Correct Registration:
claude mcp add --transport stdio --scope user <name> -- <command> [args...]
Agent MCP Access Rules
tools: Setting |
MCP Access | Example |
|---|---|---|
| Empty/Omitted | ✅ All tools | tools: |
| Explicit list (no MCP) | ❌ NO access | tools: ["Read", "Write"] |
| Explicit list (with MCP) | ✅ Listed only | tools: ["Read", "mcp__serena__*"] |
MCP Tool Naming Convention
| Registration Type | Tool Name Pattern |
|---|---|
| Plugin MCP | mcp__plugin_<server>_<server>__<tool> |
| User MCP | mcp__<server>__<tool> |
Strategy Selection (Empirically Verified)
📌 Default Recommendation: Daemon (SSE)
Daemon pattern provides the best balance: fast startup (1-2s) + zero token overhead + state sharing. Only use alternatives when specific constraints apply.
| Criteria | Daemon (SSE) ⭐ | Agent Gateway | Subprocess |
|---|---|---|---|
| Startup latency | 1-2s | ~1s | 30-60s |
| Token overhead | Zero | ~350/tool | Zero |
| State sharing | ✅ Yes | ✅ Yes | ❌ No |
| Setup effort | Medium | Low | Low |
Decision Guide
Start with Daemon (default)
│
├── Can't run background process? → Agent Gateway
│ (serverless, restricted env)
│
├── Air-gapped / offline only? → Subprocess
│ (no network, rare use)
│
└── Simple project, token OK? → Agent Gateway
(quick setup preferred)
When to Use Alternatives
| Constraint | Alternative |
|---|---|
| Cannot run background daemon | Agent Gateway |
| Serverless environment (Lambda, Cloud Functions) | Agent Gateway |
| Offline/air-gapped environment | Subprocess |
| MCP used < 2 times per session | Subprocess |
| Quick prototype, token budget OK | Agent Gateway |
Token Savings by MCP (Measured)
| MCP | Tools | Overhead | Subprocess Benefit |
|---|---|---|---|
| Serena | 29 | ~10,150 | ✅ High |
| Playwright | 25 | ~6,250 | ✅ High |
| Greptile | 12 | ~3,600 | ⚠️ Medium |
| Context7 | 2 | ~400 | ❌ Not worth it |
Rule: If tools × 350 > 5,000, consider subprocess isolation.
2-Layer Protocol
Layer 1 - Intent (common across MCPs):
| Intent | Effect | Use |
|---|---|---|
| QUERY | READ_ONLY | Search, lookup |
| ANALYZE | READ_ONLY | Interpret, impact |
| MODIFY | MUTATING | Change files |
| EXECUTE | EXTERNAL_EXEC | External calls |
Layer 2 - Action: MCP-specific tool names
Gateway Template
---
name: {mcp}-gateway
tools: # Empty = all tools including MCP
model: sonnet
---
Responsibilities:
- Context activation
- Pre-validation for MODIFY
- Atomic JSON responses
Common Issues
"MCP tools not visible"
- Cause: Session not restarted after
claude mcp add - Fix: Restart Claude Code
"Tool not found in subagent"
- Cause: Agent has explicit
tools:list without MCP - Fix: Empty
tools:or add MCP tools to list
"Wrong tool name format"
- Cause: Mixing plugin (
mcp__plugin_x_x__) and user (mcp__x__) formats - Fix: Check
claude mcp listfor actual server name prefix
Daemon Quick Start
# 1. Start daemon (one time)
uvx --from git+https://github.com/oraios/serena \
serena start-mcp-server --transport sse --port 8765 --project-from-cwd &
# 2. Register with Claude Code
claude mcp add --transport sse --scope user serena-daemon http://127.0.0.1:8765
# 3. Restart Claude Code, then use normally
References
Core Patterns
- Agent Gateway Template - Standard inherited MCP
- Subprocess Gateway - Per-call isolation
- Daemon Shared Server - Persistent HTTP/SSE server
Research & Analysis
- Subprocess Research Report - Empirical findings
- Approach Comparison Appendix - All approaches with pros/cons