Request Routing

Request Routing

MCP Catie routes MCP JSON-RPC requests to different backend services based on their content. This document explains the routing mechanism and how to configure it effectively.

Routing Basics

MCP Catie examines each incoming request to determine where it should be routed. The routing decision is based on:

1. The MCP method (e.g., resources/read, tools/call)
2. The parameters in the request
3. The client's session (if one exists)

Method-Based Routing

Different MCP methods are routed based on different parameters:

Resources/Read Routing

For resources/read requests, routing is based on the uri parameter:

{
  "jsonrpc": "2.0",
  "method": "resources/read",
  "params": {
    "uri": "weather/forecast",
    "metadata": {}
  },
  "id": 1
}

In this example, the request would be matched against patterns in the resources section of the configuration.

Tools/Call Routing

For tools/call requests, routing is based on the name parameter:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "calculator",
    "input": "1 + 1",
    "metadata": {}
  },
  "id": 2
}

This request would be matched against patterns in the tools section of the configuration.

Other Methods

Other MCP methods (like sampling/complete or roots/list) are routed to the default backend unless specific routing rules are defined for them.

Pattern Matching

MCP Catie uses regular expressions to match parameters against configured patterns:

resources:
  "^weather/.*": "http://weather-service:8080/mcp"
  "^database/.*": "http://database-service:8080/mcp"

Patterns are evaluated in no specific order, so more specific patterns should be listed first if there's potential for overlap.

Pattern Examples

Here are some example patterns and what they match:

Pattern	Matches	Doesn't Match
^weather/.*	weather/forecast, weather/current	my-weather/forecast
^files/images/.*\.jpg$	files/images/photo.jpg	files/images/photo.png
^calculator$	calculator	calculator-advanced
^search-(web|images)$	search-web, search-images	search-videos

Default Routing

If no pattern matches a request, it's routed to the default backend:

default: "http://default-service:8080/mcp"

Always configure a default backend to handle unexpected requests.

Session-Aware Routing

Once a client establishes a session with a backend, subsequent requests with the same session ID are routed to the same backend, regardless of content. This ensures conversation continuity.

Sessions are identified by the Mcp-Session-Id header in HTTP requests.

Routing Priority

The routing decision follows this priority:

1. If a session exists, route to the session's backend
2. If the method is resources/read, match the URI against resource patterns
3. If the method is tools/call, match the name against tool patterns
4. For other methods, use the default backend

Advanced Routing Techniques

Routing by Method

You can implement method-specific routing by examining the method name:

methods:
  "^sampling/complete$": "http://completion-service:8080/mcp"
  "^roots/list$": "http://roots-service:8080/mcp"

Routing by Client

You can route based on client identity using headers:

clients:
  "^api-key-1$": "http://premium-service:8080/mcp"
  "^api-key-2$": "http://standard-service:8080/mcp"

Weighted Routing

For load balancing, you can distribute traffic across multiple backends:

resources:
  "^weather/.*":
    - url: "http://weather-service-1:8080/mcp"
      weight: 70
    - url: "http://weather-service-2:8080/mcp"
      weight: 30

Routing Debugging

To debug routing issues:

1. Enable debug logging:

   logging:
     level: "debug"

2. Check the logs for routing decisions

3. Use the monitoring UI to see which backends are receiving traffic

4. Test your regex patterns with sample URIs and tool names

Best Practices

1. Be Specific: Use specific patterns to avoid routing conflicts
2. Order Matters: List more specific patterns before general ones
3. Test Thoroughly: Verify your patterns match the expected requests
4. Monitor Routing: Use the stats UI to verify routing is working correctly
5. Default Backend: Always configure a reliable default backend