catie-mcp

# MCP Catie - Context Aware Traffic Ingress Engine A lightweight, configurable reverse proxy for routing and load balancing MCP (Model Context Protocol) requests to appropriate backend services based on request content. For detailed documentation, visit [Catie MCP Documentation](https://www.catiemcp.com/docs/). ## Features - Dynamic routing of MCP JSON-RPC requests based on tool call - Concatenate tools from multiple different MCP Servers so the client gets a unified view of all tools without the user installing multiple servers. - Session-aware routing to maintain client connections to the same backend - Support for Streamable HTTP transport with SSE (Server-Sent Events) - Tool name mapping and namespacing to resolve naming conflicts between different backends - Prometheus metrics integration for observability - Containerized deployment with Docker - Basic authentication for monitoring UI ## Architecture The application is structured into several packages: - `cmd/main.go` - Application entry point with server setup - `pkg/config` - Configuration loading and management - `pkg/router` - Request routing and proxy logic - `pkg/session` - Session management for maintaining client connections - `pkg/logger` - Structured logging system - `pkg/ui` - Simple web UI for monitoring ## Configuration The router is configured using a YAML file (`router_config.yaml`). Here's an example configuration: ```yaml resources: "^weather/.*": "http://weather-service:8080/mcp" "^database/.*": "http://database-service:8080/mcp" tools: "^calculator$": "http://calculator-service:8080/mcp" "^translator$": "http://translator-service:8080/mcp" toolMappings: - originalName: "weather" targetName: "getWeather" target: "http://weather-service:8080/mcp" - originalName: "search" targetName: "googleSearch" target: "http://search-service:8080/mcp" default: "http://default-service:8080/mcp" ui: username: "admin" password: "your_secure_password" ``` The configuration consists of: - `resources`: Regex patterns for resource URIs and their target endpoints - `tools`: Regex patterns for tool names and their target endpoints - `toolMappings`: Mappings for tool name transformations to resolve naming conflicts - `default`: Fallback endpoint for requests that don't match any pattern - `ui`: Authentication credentials for the monitoring UI The configuration file is automatically reloaded when changes are detected. ## Tool Name Mapping The tool name mapping feature allows you to present a unified tool interface to clients while handling naming differences across backend MCP servers. This is useful when: - Different backends use different names for similar functionality - You want to present a simplified or standardized naming scheme to clients - You need to avoid naming conflicts between tools from different backends For each tool mapping, specify: - `originalName`: The name presented to clients - `targetName`: The actual name expected by the backend server - `target`: The URL of the target backend server When a client makes a tool call with the original name, MCProute automatically transforms it to the target name before forwarding the request to the appropriate backend. ## Installation ### Prerequisites - Go 1.18 or higher - Docker (optional, for containerized deployment) ### Building from Source 1. Clone the repository: ```bash git clone https://github.com/mclenhard/mcp-router-proxy.git cd mcp-router-proxy ``` 2. Build the application: ```bash go build -o mcp-router-proxy ./cmd/main.go ``` 3. Edit router_config.yaml to match your environment 4. Run the application: ```bash ./mcp-router-proxy ``` ### Using Docker 1. Build the Docker image: ```bash docker build -t mcp-router-proxy . ``` 2. Run the container: ```bash docker run -p 80:80 -v $(pwd)/router_config.yaml:/root/router_config.yaml mcp-router-proxy ``` ## Usage The proxy listens for MCP requests on the `/mcp` endpoint. Requests are routed based on their method and parameters: - `resources/read` requests are routed based on the `uri` parameter - `tools/call` requests are routed based on the `name` parameter - Other requests are sent to the default endpoint The proxy supports both GET and POST methods according to the MCP Streamable HTTP transport specification: - POST requests are used to send JSON-RPC messages to the server - GET requests are used to establish SSE streams for server-to-client communication ### Session Management The proxy maintains session state by tracking the `Mcp-Session-Id` header. When a client establishes a session with an MCP server through the proxy, subsequent requests with the same session ID are routed to the same backend server. ### Health Check A health check endpoint is available at `/health` which returns a 200 OK response when the service is running. ### Monitoring A simple monitoring UI is available at `/stats` which shows request statistics and routing information. This interface is protected by basic authentication using the credentials specified in the configuration file.  ### Prometheus Integration The service exposes Prometheus-compatible metrics at the `/metrics` endpoint. These metrics include: - `mcp_router_requests_total`: Total number of requests processed - `mcp_router_errors_total`: Total number of request errors - `mcp_router_requests_by_method`: Number of requests broken down by method - `mcp_router_requests_by_endpoint`: Number of requests broken down by target endpoint - `mcp_router_response_time_ms`: Average response time in milliseconds by method - `mcp_router_uptime_seconds`: Time since the router started in seconds You can configure Prometheus to scrape these metrics by adding the following to your Prometheus configuration: ```yaml scrape_configs: - job_name: 'mcp-router' scrape_interval: 15s static_configs: - targets: ['your-router-host:80'] ``` This endpoint is also protected by the same basic authentication as the stats UI. ## Development ### Project Structure ``` mcp-router-proxy/ ├── cmd/ │ └── main.go ├── pkg/ │ ├── config/ │ │ └── config.go │ ├── router/ │ │ └── router.go │ ├── session/ │ │ └── store.go │ ├── logger/ │ │ └── logger.go │ └── ui/ │ └── ui.go ├── Dockerfile ├── go.mod ├── go.sum ├── README.md └── router_config.yaml ``` ### Adding New Features 1. Fork the repository 2. Create a feature branch 3. Add your changes 4. Submit a pull request ## Roadmap The following features are planned for upcoming releases: - ~~**Add SSE Support**: Add support for SSE (Server-Sent Events) to the proxy~~ - **Complete Message Forwarding**: Ensure all MCP message types (including roots and sampling) are properly forwarded without interference - **Intelligent Caching**: Response caching with configurable TTL, cache invalidation, and support for memory and Redis backends - **Rate Limiting**: Configurable rate limiting with multiple strategies, response headers, and distributed rate limiting support - **Circuit Breaking**: Automatic detection of backend failures with fallback responses - **Request Transformation**: Modify requests before forwarding to backends - **Response Transformation**: Transform backend responses before returning to clients Development priorities are based on community feedback. Please open an issue to request features or contribute to the roadmap discussion. ## License [MIT License](LICENSE) ## Contributing Contributions are welcome! Please feel free to submit a Pull Request. ## Support For support, please open an issue in the GitHub repository or contact me at [mclenhard@gmail.com](mailto:mclenhard@gmail.com).