MCP Gateway Designer

Design and generate MCP integration systems with proper isolation, workflow enforcement, and standard protocols.

---

Process

Phase 1: Discovery (3-5 questions)

1. MCP Identification

   • What MCP server will you integrate? (name, source)
   • What tools does it provide? (list main capabilities)

2. Usage Pattern

   • How often will this MCP be used? (frequently / occasionally / rarely)
   • Are operations stateful or stateless?

3. Workflow Requirements

   • Single operation or multi-phase workflow?
   • Need quality gates between phases?

Phase 2: Strategy Selection

Based on discovery, recommend isolation strategy:

Criteria	Agent Gateway	Subprocess Isolation
Usage frequency	High	Low
Token budget	Flexible	Strict
Workflow complexity	Multi-phase	Single operation
Session continuity	Required	Not needed
Startup latency	Unacceptable	Acceptable (5-15s)

Present recommendation with trade-offs.

Phase 3: Action Mapping

Map MCP tools to 2-layer protocol:

Intent Layer (QUERY/ANALYZE/GENERATE/MODIFY/EXECUTE)
    ↓
Action Layer (MCP-specific tool names)
    ↓
Effect (READ_ONLY/MUTATING/EXTERNAL_EXEC)
    ↓
Artifact (TEXT/JSON/CODE_PY/CODE_TS/PATCH/BINARY)

Create action mapping table for user confirmation.

Phase 4: Generate Implementation

Based on strategy, generate:

For Agent Gateway:

• agents/{mcp}-gateway.md - Gateway agent definition
• hooks/hooks.json - Workflow hooks (if multi-phase)
• Action mapping reference doc

For Subprocess Isolation:

• config/{mcp}.mcp.json - Isolated MCP config
• scripts/{mcp}_gateway.py - Python wrapper
• Instructions for disabling MCP in main session

For Both:

• Consumer agent template
• Request/response examples

---

Templates

Agent Gateway Template

---
name: {mcp}-gateway
description: Central gateway for {MCP_DISPLAY_NAME} MCP tools
tools: [{mcp_tools_list}]
model: opus
---

# {MCP_DISPLAY_NAME} Gateway

[Generated gateway content based on mcp-gateway-patterns skill]

Subprocess Config Template

config/{mcp}.mcp.json:

{
  "mcpServers": {
    "{mcp}": {
      "command": "{command}",
      "args": {args_array}
    }
  }
}

Hook Template (for multi-phase workflows)

Claude Code 1.0.40+ Schema:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Task",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/scripts/workflow-gate.py",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

Gate Script Example (scripts/workflow-gate.py):

#!/usr/bin/env python3
import sys, json, os, re

data = json.load(sys.stdin)
subagent = data.get('tool_input', {}).get('subagent_type', '')

# Pattern matching for executor agents
if re.search(r'executor', subagent):
    if not os.path.exists('.workflow-plan-approved'):
        print("❌ Gate violation: Plan approval required before execution")
        sys.exit(1)  # Block

sys.exit(0)  # Allow

Note: Subagent filtering requires script-based logic since matcher only matches tool names.

---

Output Checklist

Before completion, verify:

• Strategy justified with trade-offs
• All MCP tools mapped to Intent/Action/Effect/Artifact
• Gateway agent or Python script generated
• Request/response examples provided
• Consumer agent template generated
• Hooks configured (if workflow required)
• Setup instructions clear

---

Integration Notes

With Existing skillmaker Components

• Use orchestration-patterns for multi-agent architecture
• Use skill-orchestrator-designer if consumer agents need skills

Testing Guidance

After generation:

1. Agent Gateway: Test via Task tool call
2. Subprocess: Test via python3 scripts/{mcp}_gateway.py -r '{...}'
3. Hooks: Verify gate enforcement with intentional violations

---

Error Handling

If MCP info is insufficient:

1. Ask for MCP documentation URL
2. Or ask for list of available tools
3. Generate partial design, mark unknowns for user to fill