MCP servers

Ratel Local reads Claude-Code-shaped mcpServers configuration. It connects each upstream and registers its tools in one Ratel catalog.

Its server instructions list the aggregated upstreams and tell the model to search before falling back to a generic built-in capability.

If one upstream fails to start, Ratel Local logs the failure and registers the rest. The gateway stays available.

Configuration scopes

Ratel Local merges three logical scopes. Later scopes win when the same server name appears more than once.

The CLI defaults to --scope user. Use CLI commands instead of editing these files by hand.

Project and local commands discover the project root from the current directory. Ratel prefers the nearest ancestor tree containing pnpm-workspace.yaml; otherwise it walks for .git, .mcp.json, or package.json. Run from inside the intended project.

At runtime, entries merge in this order: user → project → local. A later entry replaces an earlier entry with the same name. The old --scope global alias is rejected; use user.

Add an upstream

The command shape mirrors claude mcp add.

# stdio
ratel-mcp mcp add --scope user airtable \
  -e API_KEY=xyz -- npx -y airtable-mcp-server

# HTTP
ratel-mcp mcp add --scope user stripe \
  https://mcp.stripe.com --transport http

# SSE with a header
ratel-mcp mcp add --scope project events \
  https://example.com/sse --transport sse \
  --header "Authorization: Bearer ${EVENTS_TOKEN}"

By default, mcp add connects once and stores the upstream's server instructions as its description. Pass --description to set one yourself or --no-fetch-description to skip the probe. For HTTP or SSE, skipping the probe also skips the initial OAuth attempt.

mcp add refuses to replace a name in the target scope. Pass --force only when you intend to overwrite it; Ratel backs up the scope file first. Repeat -e KEY=VALUE for stdio environment variables or --header "Name: Value" for remote headers.

{
  "mcpServers": {
    "ev": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-everything"],
      "description": "filesystem and shell utilities"
    },
    "remote": {
      "type": "http",
      "url": "https://example.com/mcp",
      "headers": { "Authorization": "Bearer ${API_TOKEN}" }
    }
  }
}

type defaults to stdio. HTTP and SSE entries expand ${VAR} placeholders in url and headers from the process environment.

Descriptions help the agent understand each upstream before searching. They are not sent over the upstream transport.

Supported fields

Unknown transport types remain in configuration but are skipped with a warning when the gateway starts. HTTP and SSE OAuth fields are covered on OAuth upstreams.

Inspect and change servers

ratel-mcp mcp list
ratel-mcp mcp get airtable
ratel-mcp mcp get airtable --scope user

# Interactive when no field flags are supplied
ratel-mcp mcp edit --scope user --name airtable

ratel-mcp mcp edit --scope user --name airtable \
  --description "Airtable CRUD"
ratel-mcp mcp edit --scope user --name airtable \
  --env API_KEY=new-value --env OLD_KEY=
ratel-mcp mcp remove --scope user --name airtable

Without --scope, mcp get resolves the most specific matching entry: local, then project, then user. Mutating commands default to user scope and require --name for edit and remove.

Field edits support --description, --type, --command, repeated --arg, repeated --env KEY=VALUE, --cwd, --url, and repeated --header KEY=VALUE. An empty env or header value deletes that key. Use --entry-json for an entire entry; it cannot be combined with field flags.

Every write snapshots the affected configuration first. See Import or link for backup locations and host migration.

Add "skills": { "dirs": ["..."] } at the top level to use custom skill directories. Without it, Ratel Local scans ~/.ratel/skills. Prefer the commands on Managing skills when moving agent-owned skills.

Run Ratel Local yourself

Linked hosts and the plugin start Ratel Local automatically. Run it yourself when debugging or embedding it in another process.

ratel-mcp serve --config ~/.ratel/config.json
ratel-mcp serve ~/.ratel/config.json
ratel-mcp serve --auto-config
ratel-mcp serve --auto-config --project-root /path/to/project

--auto-config cannot be combined with --config. Without --project-root, it checks RATEL_PROJECT_ROOT, then CLAUDE_PROJECT_DIR, then walks up from the current directory.

Auto-config always loads the user path. When it finds a project root, it then loads the project and local paths; a missing file is treated as an empty configuration. The startup log prints the resolved root and every path.

On success, stderr includes:

[ratel] ready, N upstream server(s) configured

N is the number of configured entries, not the number that connected. Read the earlier stderr lines for failed to register, requires authorization, or unsupported transport messages.

Verify the gateway

The full tool schemas and result shapes live on Progressive disclosure.

At the MCP transport, every tools/call response JSON-serializes the result into content[0].text. Object results also appear in structuredContent. Failures return a structured { "error": "...", "isError": true } payload instead of a protocol error.

Ratel Local also registers the deprecated search_tools compatibility tool. New clients should use search_capabilities; the migration contract is on Progressive disclosure.

If you own the agent process and want to ingest an MCP server into an in-process catalog, use the inverse SDK path for TypeScript or Python.

Next steps