Project 11: MCP Tool Gateway and Capability Registry
Build a protocol-first gateway that federates MCP servers, enforces policy, and exposes a stable capability catalog for agents.
Quick Reference
| Attribute | Value |
|---|---|
| Difficulty | Level 3: Advanced |
| Time Estimate | 12-20 hours |
| Language | TypeScript (alt: Python, Go) |
| Prerequisites | Projects 1-6, JSON schema validation |
| Key Topics | MCP architecture, capability discovery, policy enforcement |
Learning Objectives
- Implement MCP host/client/server discovery and registration.
- Normalize heterogeneous tool schemas into a stable internal contract.
- Enforce policy-denied capabilities before dispatch.
- Produce request-level provenance for every tool call.
The Core Question You’re Answering
“How do you scale tool integration without coupling every agent to every tool server implementation?”
Concepts You Must Understand First
| Concept | Why It Matters | Where to Learn |
|---|---|---|
| MCP architecture | Defines standard integration boundaries | MCP architecture |
| JSON-RPC envelopes | Deterministic request/response contracts | MCP specification |
| Capability versioning | Prevents runtime schema breaks | MCP docs + semantic versioning references |
Theoretical Foundation
Agent Runtime
|
v
Gateway Catalog -> Policy Filter -> MCP Server A/B/C -> Tool Execution
A gateway acts as anti-corruption layer: it absorbs provider-specific quirks and exports stable contracts.
Project Specification
What You’ll Build
A service that:
- Discovers 3+ MCP servers
- Registers tools/resources/prompts with namespaced IDs
- Applies runtime allow/deny policy
- Logs request IDs and provenance metadata
Functional Requirements
- Dynamic server registration and health checks
- Tool schema normalization and validation
- Policy evaluation before dispatch
- Retry/timeout isolation per server
Non-Functional Requirements
- Predictable behavior under partial server failure
- Observable traces for every request
- Backward-compatible catalog evolution
Real World Outcome
$ node p11-mcp-gateway.js --goal "triage API outage"
[registry] discovered 3 servers
[catalog] tools=14 resources=22
[policy] denied=2 allowed=12
[dispatch] get_alerts -> read_runbook -> summarize
[artifact] incident_summary.md and provenance_trace.json
Architecture Overview
┌──────────┐ register ┌──────────────┐
│ MCP A/B/C│─────────────▶│ Gateway Core │
└──────────┘ ├──────────────┤
│ Policy Engine│
│ Schema Guard │
│ Trace Export │
└──────┬───────┘
▼
Agent Runtime
Implementation Guide
Phase 1: Catalog + Validation
- Implement registration and namespaced IDs.
- Checkpoint: deterministic tool list export.
Phase 2: Policy + Dispatch
- Add allow/deny and per-tool risk classes.
- Checkpoint: blocked actions never execute.
Phase 3: Observability + Replay
- Add request IDs, traces, and replay utility.
- Checkpoint: one failed run is fully reproducible.
Testing Strategy
- Unit: schema normalization, policy decisions
- Integration: dispatch to each server type
- Failure tests: one server down, malformed schema, timeout bursts
Common Pitfalls & Debugging
| Pitfall | Symptom | Fix |
|---|---|---|
| Tool name collisions | nondeterministic routing | enforce namespaced IDs |
| Hidden schema drift | runtime parse errors | strict contract checks at registration |
| Policy bypass | unsafe tool calls execute | evaluate policy at dispatch boundary |
Interview Questions They’ll Ask
- Why MCP vs bespoke tool adapters?
- How do you safely version tool contracts?
- What belongs in gateway policy vs agent prompt?
- How do you debug partial federation outages?
Hints in Layers
- Hint 1: Build one-server happy path first.
- Hint 2: Add schema registry before routing logic.
- Hint 3: Fail closed on unknown capabilities.
- Hint 4: Make every request replayable by ID.
Submission / Completion Criteria
Minimum Completion
- 3 MCP servers registered and callable via one gateway
Full Completion
- Policy enforcement + schema validation + traceability
Excellence
- Hot-reload of server capabilities without agent downtime