Home › Connect › OpenClaw

Connect OpenClaw to an MCP gateway with OAuth

OpenClaw's MCP client speaks Streamable HTTP with managed OAuth tokens (v1.5.0+). Three commands and your personal agent gets a governed, scope-filtered tool catalog — instead of raw API keys scattered in its config.

TL;DR

openclaw mcp add cortex \
  --url https://mcp.cortex-gateway.dev/mcp \
  --transport streamable-http \
  --auth oauth

openclaw mcp login cortex
openclaw mcp doctor --probe

Steps

Add the server with the command above (replace the URL with your own gateway's /mcp endpoint). Optional flags: --timeout 20 --connect-timeout 5.
Authenticate: openclaw mcp login cortex opens the gateway's OAuth flow (magic-link signup on the public demo, then the consent screen). On a headless machine, use openclaw mcp login cortex --code <authorization-code> to paste the code back.
Verify: openclaw mcp doctor --probe should show the server connected and list the federated tools (demo_echo, demo_get_time, whoami, ...).

Equivalent JSON config

If you manage openclaw.json by hand:

{
  "mcp": {
    "servers": {
      "cortex": {
        "url": "https://mcp.cortex-gateway.dev/mcp",
        "transport": "streamable-http",
        "auth": "oauth",
        "timeout": 20,
        "connectTimeout": 5,
        "sslVerify": true
      }
    }
  }
}

OAuth tokens are stored by OpenClaw and refreshed automatically after openclaw mcp login.

Why this pairing works well

OpenClaw is a personal, always-on agent — exactly the kind of client you don't want holding static API keys to everything. Behind a gateway, it holds a single short-lived OAuth token bound to your identity: every backend applies your permissions, the audit trail records what the agent actually did, and revoking the grant at the OAuth server cuts everything at once.

Deploying OpenClaw for a company rather than for yourself? Its own docs declare one instance single-user, and the default shared install fails the questions access audits ask — see OpenClaw in a company: what an auditor will ask (ISO 27001, SOC 2, GDPR, and the installer's checklist).

Troubleshooting

Symptom	Likely cause
Add succeeds, login fails	Check the gateway's discovery answers: `curl https://mcp.cortex-gateway.dev/.well-known/oauth-protected-resource` must list the authorization server.
Probe shows 0 tools	Your account has none of the required scopes — call the `whoami` builtin to see what your token carries.
Old OpenClaw version	Streamable HTTP is primary from v1.5.0; earlier versions can use `--transport sse` (deprecated) or should upgrade.

Self-hosting your own gateway: github.com/wellknownmcp/cortex-gateway.