Skip to main content
Providers represent MCP server connections in UMCP. Each provider defines how to connect to an MCP server, what transport method to use, and which tools to expose.

​
Provider Configuration

Providers are defined in the providers array within each category: 
{
  "categories": {
    "web_search": {
      "providers": [
        {
          "name": "brave",
          "transport": "stdio",
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-brave-search"],
          "env": {
            "BRAVE_API_KEY": "your-api-key"
          },
          "tools": [
            { "upstream": "search", "alias": "search" }
          ]
        }
      ]
    }
  }
}

​
Schema Reference

​
name
string
required
Provider name used as the second namespace segment: {category}.{provider}.{tool}Pattern: [a-zA-Z0-9_-]+Must be unique within the category. Can be reused across different categories.Examples:
  • ✅ brave
  • ✅ server-1
  • ✅ api_v2
  • ❌ my.provider (contains dot)
  • ❌ my provider (contains space)
​
transport
enum
default:"stdio"
Transport method for connecting to the MCP serverOptions:
  • stdio - Standard input/output (most common)
  • sse - Server-Sent Events
  • streamable-http - HTTP streaming
Default: stdio
​
command
string
Command to execute for stdio transportRequired when: transport is stdio (or omitted)Examples:
  • "npx"
  • "node"
  • "/usr/local/bin/mcp-server"
  • "python"
​
args
array
Array of command-line arguments for the commandExample:
["--yes", "@modelcontextprotocol/server-brave-search"]
​
url
string
URL for sse or streamable-http transportRequired when: transport is sse or streamable-httpMust be: A valid URLExample:
"https://linear-mcp.example.com/mcp"
​
env
object
Environment variables to pass to the providerSee Environment Variables for details.
​
tools
array
Array of tool mappings controlling which tools are exposedIf omitted: UMCP auto-discovers all tools from the providerIf provided: Only explicitly mapped tools are exposedSee Tool Configuration for details.

​
Transport Methods

​
stdio (Standard Input/Output)

The most common transport method. UMCP spawns a child process and communicates via stdin/stdout. 
{
  "name": "brave",
  "transport": "stdio",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-brave-search"],
  "env": {
    "BRAVE_API_KEY": "your-api-key"
  }
}
The transport field defaults to "stdio" if omitted, so you can omit it for stdio providers.
Requirements:
  • command is required
  • args is optional
  • url should not be specified

​
sse (Server-Sent Events)

Connect to a remote MCP server using Server-Sent Events: 
{
  "name": "remote_api",
  "transport": "sse",
  "url": "https://api.example.com/mcp/sse"
}
Requirements:
  • url is required
  • command and args should not be specified

​
streamable-http (HTTP Streaming)

Connect to a remote MCP server using HTTP streaming: 
{
  "name": "linear",
  "transport": "streamable-http",
  "url": "https://linear-mcp.example.com/mcp"
}
Requirements:
  • url is required
  • command and args should not be specified

​
Provider Naming Rules

Provider names must follow the same constraints as category names: Pattern: [a-zA-Z0-9_-]+ Allowed:
  • Lowercase letters: a-z
  • Uppercase letters: A-Z
  • Numbers: 0-9
  • Underscore: _
  • Hyphen: -
Not allowed:
  • Dots (.)
  • Spaces
  • Special characters
Provider names must be unique within each category, but can be reused across different categories.

​
Examples

​
NPM Package via npx

{
  "name": "brave",
  "transport": "stdio",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-brave-search"],
  "env": {
    "BRAVE_API_KEY": "your-api-key"
  }
}

​
Node.js Script

{
  "name": "custom_server",
  "transport": "stdio",
  "command": "node",
  "args": ["/path/to/server.js"],
  "env": {
    "API_KEY": "your-api-key"
  }
}

​
Python Script

{
  "name": "python_server",
  "transport": "stdio",
  "command": "python",
  "args": ["/path/to/server.py"],
  "env": {
    "PYTHONUNBUFFERED": "1"
  }
}

​
Remote HTTP Server

{
  "name": "linear",
  "transport": "streamable-http",
  "url": "https://linear-mcp.example.com/mcp",
  "tools": [
    {
      "upstream": "create_issue",
      "alias": "add_task"
    }
  ]
}

​
Multiple Providers in One Category

{
  "categories": {
    "web_search": {
      "providers": [
        {
          "name": "brave",
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-brave-search"],
          "env": { "BRAVE_API_KEY": "key1" }
        },
        {
          "name": "tavily",
          "command": "npx",
          "args": ["-y", "tavily-mcp"],
          "env": { "TAVILY_API_KEY": "key2" }
        }
      ]
    }
  }
}

​
Auto-Discovery

If you omit the tools field, UMCP automatically discovers all tools from the provider: 
{
  "name": "tavily",
  "command": "npx",
  "args": ["-y", "tavily-mcp"],
  "env": {
    "TAVILY_API_KEY": "your-api-key"
  }
  // tools omitted -> auto-discover all tools
}
Use auto-discovery during development to explore what tools a provider offers. Switch to explicit tool mappings in production for better control.

​
Validation Rules

UMCP enforces these validation rules for providers:
  1. Name required: Every provider must have a name
  2. Valid naming: Provider names must match [a-zA-Z0-9_-]+
  3. Unique names: Provider names must be unique within each category
  4. Transport requirements:
    • stdio requires command
    • sse requires url
    • streamable-http requires url
  5. Strict mode: Unknown fields will cause validation errors

​
Error Messages

​
Missing command for stdio

Config validation failed: provider.command is required when transport is stdio
Solution: Add a command field to your provider configuration.

​
Missing URL for HTTP transports

Config validation failed: provider.url is required when transport is sse or streamable-http
Solution: Add a url field to your provider configuration.

​
Invalid provider name

Config validation failed: provider.name must match [a-zA-Z0-9_-]+
Solution: Rename the provider to use only allowed characters.

​
Duplicate provider name

Config validation failed: duplicate provider name 'brave' within one category
Solution: Choose a unique name for each provider within the category.

​
Next Steps

Configure Tools

Control which tools are exposed from providers

Environment Variables

Configure secrets and API keys

Build docs developers (and LLMs) love

Get started for freeTalk to us