Skip to main content

​
Welcome to UMCP

UMCP (Unified MCP) solves MCP configuration sprawl by aggregating multiple upstream MCP servers behind one server entry. Instead of managing dozens of separate server configurations, UMCP gives you a single unified endpoint with intelligent namespacing and advanced features.

Installation

Get started with npm, npx, or GitHub installation

Quick Start

Launch UMCP in under 5 minutes with real examples

Configuration

Configure providers, namespaces, and tool mappings

CLI Reference

Complete CLI command reference and flags

​
Core Features

UMCP exposes all upstream tools with a predictable three-segment naming convention:
{category}.{provider}.{tool}
For example:
  • web_search.brave.search
  • web_search.tavily.search
  • project_mgmt.linear.add_task
This eliminates naming conflicts and makes it clear which provider each tool comes from.
Map upstream tool names to custom aliases in your config:
"tools": [
  {
    "upstream": "create_issue",
    "alias": "add_task",
    "enabled": true
  }
]
This is especially useful when upstream tools have incompatible characters like dots in their names.
Distribute API calls across multiple keys automatically:
"env": {
  "BRAVE_API_KEY": [
    "key_1_prod",
    "key_2_prod",
    "key_3_prod"
  ]
}
UMCP rotates through keys on each invocation, perfect for rate limiting and load distribution. State is in-memory and resets on process restart.
UMCP bridges different transport protocols:Serve Transport (how clients connect to UMCP):
  • stdio - Standard input/output
  • http - Streamable HTTP endpoint
Upstream Transport (how UMCP connects to providers):
  • stdio - Command-line MCP servers
  • sse - Server-Sent Events
  • streamable-http - HTTP-based MCP servers
Mix and match as needed for your infrastructure.

​
Before and After

​
Before: Configuration Sprawl

Managing multiple MCP servers separately in your host config: 
{
  "mcpServers": {
    "brave": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": { "BRAVE_API_KEY": "..." }
    },
    "tavily": {
      "command": "npx",
      "args": ["-y", "tavily-mcp"],
      "env": { "TAVILY_API_KEY": "..." }
    },
    "linear": {
      "url": "https://linear-mcp.example.com/mcp"
    }
  }
}

​
After: Single Unified Endpoint

One UMCP entry that manages everything: 
{
  "mcpServers": {
    "umcp": {
      "command": "npx",
      "args": ["-y", "github:grittyninja/umcp", "serve", "--transport", "stdio"]
    }
  }
}
All tools are now namespaced and accessible through the single UMCP endpoint:
  • web_search.brave.search
  • web_search.tavily.search
  • project_mgmt.linear.add_task
UMCP manages all provider connections, environment variables, and tool discovery internally via the ~/.config/umcp/umcp.jsonc configuration file.

​
Naming Rules

To ensure canonical names remain deterministic as exactly three segments, UMCP enforces strict naming rules:
​
category
string
required
Must match [a-zA-Z0-9_-]+ (alphanumeric, underscores, hyphens only)
​
provider
string
required
Must match [a-zA-Z0-9_-]+ (alphanumeric, underscores, hyphens only)
​
tool alias
string
Must match [a-zA-Z0-9_-]+ (alphanumeric, underscores, hyphens only)
If an auto-discovered upstream tool name contains unsupported characters (like dots), UMCP requires an explicit tools mapping with a valid alias.

​
Structured Logging

UMCP emits structured JSON logs to stderr for observability: 
{
  "level": "info",
  "event": "config.loaded",
  "message": "Loaded umcp config",
  "configPath": "/Users/you/.config/umcp/umcp.jsonc",
  "categories": 2
}
Available log events:
  • config.loaded, config.created, config.invalid
  • provider.connected, provider.disconnected
  • tool.discovered, tool.registered, tool.called
  • env.rotated
  • dry_run.complete

​
Requirements

Node.js

Version 20 or higher required

Config Format

Only .jsonc files supported (JSON with comments)

​
Next Steps

1

Install UMCP

Choose your preferred installation method: npm, npx, or GitHub
2

Configure Providers

Set up your MCP providers in ~/.config/umcp/umcp.jsonc
3

Start Using

Run umcp serve and connect from your MCP host

Ready to get started?

Install UMCP now and consolidate your MCP servers

Build docs developers (and LLMs) love

Get started for freeTalk to us