Architecture

Architecture Overview

MCP Catie is designed with a modular architecture that separates concerns and allows for easy extension. This document provides an overview of the system architecture and how the components interact.

High-Level Architecture

At a high level, MCP Catie consists of the following components:

1. HTTP Server: Handles incoming HTTP requests
2. Router: Determines where to route requests based on content
3. Session Manager: Tracks client sessions
4. Proxy Handler: Forwards requests to backend services
5. Configuration Manager: Loads and monitors configuration
6. Monitoring System: Collects and exposes metrics

Here's a diagram of how these components interact:

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  HTTP       │     │  Router     │     │  Backend    │
│  Client     │────▶│  Proxy      │────▶│  Services   │
└─────────────┘     └─────────────┘     └─────────────┘
                          │
                          │
                    ┌─────▼─────┐
                    │ Session   │
                    │ Manager   │
                    └─────┬─────┘
                          │
                    ┌─────▼─────┐
                    │ Config    │
                    │ Manager   │
                    └─────┬─────┘
                          │
                    ┌─────▼─────┐
                    │ Monitoring│
                    │ System    │
                    └───────────┘

Component Details

HTTP Server

The HTTP server is responsible for:

• Listening for incoming HTTP requests
• Handling different HTTP methods (GET, POST)
• Managing connection lifecycle
• Implementing the MCP Streamable HTTP transport

Router

The router analyzes incoming MCP requests and determines where they should be forwarded. It:

• Parses JSON-RPC requests
• Extracts method and parameters
• Matches against configured patterns
• Selects the appropriate backend service

Session Manager

The session manager:

• Tracks client sessions using the Mcp-Session-Id header
• Ensures requests from the same session go to the same backend
• Handles session expiration and cleanup

Proxy Handler

The proxy handler:

• Forwards requests to backend services
• Manages connection pooling
• Handles timeouts and errors
• Maintains SSE streams

Configuration Manager

The configuration manager:

• Loads the initial configuration
• Monitors the configuration file for changes
• Reloads configuration when changes are detected
• Validates configuration

Monitoring System

The monitoring system:

• Collects metrics about request handling
• Exposes Prometheus-compatible metrics
• Provides a web UI for monitoring
• Implements health checks

Package Structure

MCP Catie is organized into the following packages:

mcp-catie/
├── cmd/
│   └── main.go           # Application entry point
├── pkg/
│   ├── config/           # Configuration management
│   │   └── config.go
│   ├── router/           # Request routing logic
│   │   └── router.go
│   ├── session/          # Session management
│   │   └── store.go
│   ├── proxy/            # Proxy functionality
│   │   └── handler.go
│   ├── metrics/          # Metrics collection
│   │   └── metrics.go
│   ├── logger/           # Structured logging
│   │   └── logger.go
│   └── ui/               # Web UI
│       └── ui.go

Request Flow

1. Client sends an MCP request to the proxy
2. HTTP server receives the request
3. Router extracts method and parameters
4. Router checks for an existing session
5. Router selects a backend based on request content and session
6. Proxy handler forwards the request to the selected backend
7. Proxy handler streams the response back to the client
8. Metrics are collected about the request

Design Principles

MCP Catie follows these design principles:

1. Separation of Concerns: Each component has a specific responsibility
2. Configuration Over Code: Behavior is controlled by configuration
3. Observability: All components expose metrics and logs
4. Resilience: Handles errors gracefully and maintains service
5. Simplicity: Focuses on doing one thing well

Performance Considerations

MCP Catie is designed to be lightweight and efficient:

• Uses connection pooling to reduce overhead
• Minimizes memory allocations in the request path
• Employs efficient regex matching
• Implements proper timeout handling
• Uses Go's concurrency model for parallel request handling