Chkim Su Forge Editor MCP Gateway Patterns

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

Correct Registration:

claude mcp add --transport stdio --scope user <name> -- <command> [args...]

Agent MCP Access Rules

MCP Tool Naming Convention

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.

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

Token Savings by MCP (Measured)

Rule: If tools × 350 > 5,000, consider subprocess isolation.

2-Layer Protocol

Layer 1 - Intent (common across MCPs):

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

• 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

Setup & Validation

• Protocol Schema
• Setup Automation
• Validation Patterns

Converted and distributed by TomeVault — claim your Tome and manage your conversions.