Core Concepts

This guide explains the fundamental concepts you need to understand when working with RouterMCP.

What is MCP?

The Model Context Protocol (MCP) is an open standard developed by Anthropic for connecting AI assistants to external tools and data sources. It defines how AI clients communicate with tool servers.

An MCP server can provide:

• Tools - Functions the AI can call (e.g., create_file, search_web)
• Resources - Data the AI can read (e.g., files, database records)
• Prompts - Pre-defined prompt templates

RouterMCP as a Gateway

RouterMCP acts as a gateway that sits between your AI client and multiple upstream MCP servers:

┌─────────────┐     ┌──────────────┐     ┌─────────────────┐
│  AI Client  │────▶│  RouterMCP   │────▶│  MCP Server 1   │
│  (Claude)   │     │   Gateway    │────▶│  MCP Server 2   │
└─────────────┘     └──────────────┘────▶│  MCP Server 3   │
                                         └─────────────────┘

Instead of configuring each MCP server individually in your AI client, you configure RouterMCP once, and it handles:

1. Aggregation - Combines tools from all connected servers
2. Namespacing - Prefixes tools with server names to avoid conflicts
3. Routing - Forwards tool calls to the correct upstream server
4. Filtering - Controls which tools are exposed

CLI vs Cloud

RouterMCP is available in two forms:

RouterMCP CLI (Self-Hosted)

The CLI is an npm package that runs locally on your machine:

npm install -g routermcp

Best for:

• Local development
• Privacy-sensitive workloads
• Connecting to stdio-based MCP servers
• Full control over your environment

Features:

• Stdio and HTTP transports
• Tool/resource/prompt filtering
• Code Mode (JavaScript sandbox)
• Cloudflare Tunnels integration
• Environment variable injection

RouterMCP Cloud (Hosted)

RouterMCP Cloud is a hosted service with a dashboard UI:

Best for:

• Team collaboration
• Remote/shared access
• OAuth-enabled servers
• Production deployments

Features:

• Web dashboard
• Team management
• API key authentication
• OAuth upstream handling
• Audit logs
• Server registry

Tool Namespacing

When you connect multiple MCP servers, their tools might have conflicting names. RouterMCP solves this with namespacing.

If you have:

• Server github with tool create_issue
• Server jira with tool create_issue

RouterMCP exposes them as:

• github.create_issue
• jira.create_issue

Transports

RouterMCP supports multiple transport protocols:

The CLI can operate in either stdio mode (for MCP clients that spawn processes) or HTTP mode (for remote connections).

Filtering

RouterMCP provides powerful filtering to control which tools are exposed:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "filter": {
        "tools": {
          "include": ["read_*", "list_*"],
          "exclude": ["*delete*", "*write*"]
        }
      }
    }
  }
}

This exposes only read and list operations, blocking any delete or write tools.

Sessions

When running in HTTP mode, RouterMCP manages sessions for each connected client:

• Sessions maintain state across requests
• Multiple clients can connect simultaneously
• Sessions timeout after inactivity (default: 5 minutes)
• Each session gets its own connection to upstream servers

Next Steps

• First Project Tutorial - Step-by-step project setup
• CLI Configuration - Full configuration reference
• Cloud - RouterMCP Cloud documentation