Phase 1: Implement Core MCP Aggregation

[AlexMikhalev]

Goal

Enable multiple MCP server aggregation within roles

Tasks

• Create new crate terraphim_mcp_proxy
• Implement McpProxy struct for server aggregation
• Add namespace support for grouping MCP servers
• Implement tool prefixing (ServerName__toolName)
• Build routing logic to direct tool calls to correct servers
• Update terraphim_config with McpNamespace struct
• Extend Role to support multiple MCP namespaces
• Add tool override configuration
• Support environment variable interpolation
• Create McpServerPool for connection management
• Add idle session pre-allocation
• Implement health monitoring and auto-reconnection
• Add timeout and retry logic

Success Criteria

• Can aggregate multiple MCP servers into a single namespace
• Tool calls route to correct servers based on prefix
• Connection pooling reduces latency
• Configuration supports namespaces

Timeline

Week 1-2

Related to MetaMCP feature parity: https://github.com/metatool-ai/metamcp

[AlexMikhalev]

Phase 1 Progress Update

✅ Completed: Core MCP proxy infrastructure

Implemented Components

New Crate: terraphim_mcp_proxy

• Namespace management for grouping MCP servers
• Tool prefixing (ServerName__toolName) to avoid conflicts
• Tool routing logic with ToolRouter
• Connection pool with health monitoring (McpServerPool)
• Environment variable interpolation (${VAR_NAME})
• Tool override support (rename/redescribe/enable/disable)

Key Features

• Support for STDIO, SSE, HTTP, and OAuth transports
• Server health monitoring and statistics tracking
• Namespace enable/disable support
• Tool-level enable/disable control
• Configurable health check intervals

Testing

• 17 unit tests covering all core functionality
• All tests passing

Next Steps

• Integrate McpProxy into terraphim_config
• Add namespace support to Role configuration
• Implement MCP endpoint exposure (Phase 2)
• Add API key authentication (Phase 2)

Branch: feature/metamcp-integration
Commit: f65ddb2

[AlexMikhalev]

Phase 1 Complete ✅

Summary

Successfully implemented core MCP proxy infrastructure for aggregating multiple MCP servers.

Completed Features

New Crate: terraphim_mcp_proxy ()

• ✅ Namespace management for grouping MCP servers
• ✅ Tool prefixing (ServerName__toolName) to avoid conflicts
• ✅ Tool routing with ToolRouter
• ✅ Connection pool with health monitoring (McpServerPool)
• ✅ Environment variable interpolation (${VAR_NAME})
• ✅ Tool override support (rename/redescribe/enable/disable)
• ✅ JSON Schema support for config integration
• ✅ Support for STDIO, SSE, HTTP, and OAuth transports

Configuration Integration

• ✅ Added mcp-proxy feature to terraphim_config
• ✅ Added mcp_namespaces field to Role struct (feature-gated)
• ✅ Feature-gated with mcp-proxy feature flag
• ✅ Backward compatible with existing configurations

Documentation & Examples

• ✅ Example configuration file (examples/mcp_namespace_config.json)
• ✅ Comprehensive README (examples/MCP_NAMESPACE_README.md)
• ✅ Examples for all transport types
• ✅ Tool override examples

Testing

• ✅ 17 unit tests passing
• ✅ All crates build successfully
• ✅ Config integration tested

Next Steps (Phase 2)

See #279 for:

• Integrate McpProxy into terraphim_middleware
• Implement MCP endpoint exposure (/metamcp/{name}/sse)
• Add API key authentication
• Database migration for MCP tables

How to Use

1. Enable the feature:

cargo build --features mcp-proxy

2. Add namespaces to your role config:

{
  "mcp_namespaces": [{
    "name": "dev-tools",
    "servers": [...],
    "tool_overrides": {...}
  }]
}

See examples/MCP_NAMESPACE_README.md for detailed documentation.

Branch: feature/metamcp-integration
Commits: f65ddb2, 7d70521, and latest