mcp-gateway-patterns

MCP Gateway design patterns for Agent Gateway, Subprocess, and Daemon isolation. Use when designing MCP integrations.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026⬇️1downloads

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.
namemcp-gateway-patterns
descriptionMCP 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:

  1. Context activation
  2. Pre-validation for MODIFY
  3. 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 list for 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

Research & Analysis

Setup & Validation