docs / mcp servers

MCP servers

Wombat is an MCP client. Local stdio servers and remote HTTP/SSE servers both work, their tools appear as mcp__server__tool, and every server can hold its own permission gate.

Add a server

# local stdio
wombat mcp add playwright -- npx -y @playwright/mcp@latest
wombat mcp add github --env GITHUB_TOKEN=... -- \
  npx -y @modelcontextprotocol/server-github

# remote HTTP with a static token
wombat mcp add context7 --url https://mcp.context7.com/mcp
wombat mcp add github --url https://api.githubcopilot.com/mcp/ \
  --header 'Authorization=Bearer ${GITHUB_TOKEN}'

flag	meaning
`--url`	Remote endpoint. Must be HTTPS unless it is a loopback address.
`--type` / `--transport`	`stdio`, `http` or `sse`.
`--cwd`	Working directory for a local server.
`--env`, `--header`	Environment or request headers, repeatable, with `${VAR}` expansion.
`--class`	`mcp`, `read`, `network`, `write` or `edit` — the permission class for its tools.
`--workers`	Allow delegated workers to use this server's tools. Without it, the server is lead-only.
`--timeout`, `--call-timeout`	Startup timeout (default 15s) and per-call timeout in seconds.
`--no-oauth`	Disable interactive OAuth for a remote server.
`--oauth-redirect`, `--oauth-client-id`, `--oauth-client-secret`	Pre-registered OAuth client details.

Manage and inspect

wombat mcp list
wombat mcp test [name...]      # connect, list tools, show stderr
wombat mcp enable <name>
wombat mcp disable <name>
wombat mcp remove <name>
wombat mcp import .mcp.json    # Claude/Cursor mcpServers, or OpenCode mcp.servers

test is the first thing to run when a server misbehaves: it connects, lists tools, and prints the server's own stderr. Use --timeout 60 for a slow first npx download and --call-timeout 600 for slow tools.

OAuth

wombat mcp add notion --url https://mcp.notion.com/mcp
wombat mcp login notion
wombat mcp test notion
wombat mcp logout notion

Login opens the browser, completes a loopback callback with PKCE and state checks, and stores access and refresh tokens in ~/.wombat/mcp-auth/ with 0600 permissions. Tokens refresh automatically. Agent startup only uses cached tokens and tells you to run wombat mcp login <server> when one is missing. Logging out, updating or removing a server clears the saved login.

Use "oauth": false for API-key servers, or set oauth_client_id, oauth_client_secret, oauth_scopes and oauth_redirect_url for a pre-registered client. Some providers only register approved clients; a PAT or a local server is the way around that.

Config and permissions

Servers live under mcp_servers in ~/.wombat/config.json:

{
  "mcp_servers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
      "class": "read"
    },
    "context7": {
      "type": "http",
      "url": "https://mcp.context7.com/mcp",
      "headers": { "Authorization": "Bearer ${CONTEXT7_API_KEY}" }
    }
  }
}

${VAR}, ${VAR:-default} and {env:VAR} expand when the server starts, so secrets stay in the environment. MCP calls are gated by mcp:<server>, falling back to mcp, which defaults to ask.

wombat config set permissions.mcp allow
wombat config set permissions.mcp:github ask

Local servers run as you, with your environment. Only add servers you trust, and keep them at ask until you have watched them work. A --class read server is the safe default for a delegated scout, and only servers passed with --workers reach the fleet at all.

In chat

/mcp shows every attached server, its tools, its status and this session's call counts. /toolset lists the tools the session can actually use, with the permission gate for each.

Which servers are worth it

Add two or three, not seven. Every server puts its tool schemas in front of the model, and past a point more tools makes the choice worse, not better. The MCP catalog sorts servers by genre — code, design, art, docs, data and ops — with the exact wombat mcp add line for each.