Skip to main content
Ultra proxies requests to one or more upstream MCP servers. Servers can use stdio transport (local commands) or HTTP transport (remote URLs).

​
Adding Servers from Registry

The easiest way to add servers is from the MCP registry: 
# Search for servers
ultra search filesystem

# Add by name (searches registries)
ultra add filesystem

# Add by full package name
ultra add @modelcontextprotocol/server-filesystem

# Add with a custom name
ultra add @modelcontextprotocol/server-filesystem --name myfiles
When adding from the registry, Ultra automatically tests the connection, detects authentication requirements, and prompts for any required configuration (API keys, file paths, etc.).

​
Adding Remote Servers by URL

Add HTTP-based MCP servers directly by URL: 
# Add a remote server
ultra add https://mcp.slack.com/mcp

# With a custom name
ultra add https://remote.example.com/mcp --name myserver
Ultra auto-detects transport type and authentication requirements. If the server requires OAuth, you’ll be prompted to authorize when it’s first used. For token-based auth, Ultra prompts for the token during setup.

​
Adding Servers Manually

Use ultra servers add for full control: 
# Stdio transport (local command)
ultra servers add filesystem \
  --command npx \
  --args "-y @modelcontextprotocol/server-filesystem /tmp"

# HTTP transport (remote URL)
ultra servers add remote-api --url https://mcp.example.com/sse

# With environment variables
ultra servers add github \
  --command npx \
  --args "-y @modelcontextprotocol/server-github" \
  --env "GITHUB_TOKEN=ghp_xxx"

# Add in disabled state
ultra servers add test-server --command ./test-server --disabled

​
Managing Servers

# List all servers
ultra servers

# Enable/disable
ultra servers enable filesystem
ultra servers disable filesystem

# Remove
ultra servers remove filesystem
ultra servers remove filesystem --force  # Skip confirmation

​
Stdio vs HTTP Transport

​
Stdio Transport

For servers that run as local processes. Ultra spawns the process and communicates over stdin/stdout. 
upstream:
  filesystem:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    env:
      NODE_ENV: production
    enabled: true

​
HTTP Transport

For remote servers. Ultra connects over HTTP/SSE. 
upstream:
  notion:
    url: "https://mcp.notion.so"
    headers:
      Authorization: "Bearer secret_xxx"
    enabled: true

​
Authentication

​
Token-Based Auth

Set auth tokens for HTTP servers: 
# Set during add (interactive)
ultra add https://mcp.example.com/sse

# Set after adding
ultra config set-token my-server YOUR_TOKEN

# Set a custom header
ultra config set-header my-server X-API-Key YOUR_KEY
Tokens are stored as Authorization: Bearer {token} headers in the config file.

​
OAuth2

Ultra supports OAuth2 authentication for upstream servers that require it. The OAuth flow is handled automatically at runtime — when a server requires authorization, Ultra opens a browser for you to complete the flow and stores the tokens for future requests.

​
Environment Variables

For stdio servers, pass secrets via environment variables instead of hardcoding them in args: 
upstream:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_TOKEN: "ghp_xxxxxxxxxxxx"
    enabled: true