Reachable from anywhere
MCP Relay
Connect ChatGPT, Claude or Codex to your OpenClaw conversations without opening a Gateway port or sharing your Gateway password.
Read when: You want to talk to your agents from ChatGPT, Claude or Codex.
MCP Relay is a bundled plugin. When it is on, the Gateway keeps an outbound WebSocket to the relay at https://mcp.openclaw.ai. ChatGPT, Claude and Codex add https://mcp.openclaw.ai/mcp as an MCP server. You approve each app on your own Gateway, choose how much it may do, and revoke it in Connected apps. The app never receives your Gateway token or password. The connection is not end-to-end encrypted: the relay sees what passes through it.
How it works
The connection
- The Gateway dials
wss://mcp.openclaw.ai/v1/gateway/connectwith its public key. - The relay sends a challenge; the Gateway signs it; the relay answers with the Gateway's ID.
- The socket pings every 30 seconds and reconnects with backoff from 1 to 60 seconds.
From extensions/mcp-relay/src/service.ts:338-501 and src/protocol.ts.
Two ways to approve an app
| Pair with code | Sign in with your Gateway | |
|---|---|---|
| Start | Connected apps → Pair with code, or openclaw mcp-relay pair | On the relay page, Sign in with your Gateway and enter your Control UI address |
| You confirm | By entering the code XXXXX-XXXXX on the relay page | On your Gateway: "Connect {App}?" → Allow or Deny |
| Lifetime | Code: single use, 10 minutes | Request: 10 minutes. Grant: 30-day refresh limit |
| Stored | Only the code's hash. Grants and the relay identity live in the Gateway's state database (mcp-relay-authority). | |
What an app can do
| Operation | What it does | Limits |
|---|---|---|
status | Gateway name, version and agents | |
conversations.list | Titles, previews, agent, last update | Up to 50; search up to 200 characters |
conversation.read | User and assistant text, page by page | Up to 100 per page |
message.send | Sends to a conversation, or starts a new one | 8,000 characters; waits up to 50 seconds for a reply |
reply.get | Checks on a reply still running |
New conversations go to the agent the app names, then the plugin's agentId, then your default agent. Apps cannot call other Gateway methods. Only ChatGPT and Codex get the full Control UI.
Access levels
| Shown as | Means |
|---|---|
| Read and write | Read conversations and send messages within your access. The default. |
| Full role access | Everything your role can do, including Gateway administration and approvals. |
An app's real access is always the grant and your own current permissions together, checked on every request.
What you need
| What | Why |
|---|---|
| Admin rights on the Gateway | Enabling a plugin and pairing need operator.admin. |
Outbound HTTPS to mcp.openclaw.ai | The Gateway dials the relay. No inbound port. |
| A Gateway that accepts the grant | Token or password auth for owner grants. Trusted-proxy Gateways need Cloudflare Access and gateway.roles for person grants. See On Urbicana today. |
| An app that takes custom MCP servers | A ChatGPT plugin, a Claude custom connector, or Codex. |
Turn it on
- Control UIOpen Plugins, choose MCP Relay, click Enable. Or in a terminal:
Follow any restart instruction it prints.openclaw plugins enable mcp-relay - TerminalCheck the relay connection:
It showsopenclaw mcp-relay statusconnectedand the Gateway's ID. - Control UIIn the sidebar, Pages → Connected apps. You see "No connected apps yet".
- ClaudeIn Connected apps, click Pair with code, keep Read and write, click Create pairing code. In Claude, add a custom connector with this address:
On the relay page, enter the code and connect.https://mcp.openclaw.ai/mcp - ChatGPTAdd the same address as a plugin. On the relay page choose Sign in with your Gateway and enter your Control UI address. Your Gateway shows "Connect ChatGPT?"; click Allow.
- Codex
codex mcp add openclaw --url https://mcp.openclaw.ai/mcpcodex mcp login openclaw - The appAsk: "List my OpenClaw conversations." Then: "Start a conversation with my default agent and ask it what it can do."
Config, if you prefer it:
plugins: { entries: { "mcp-relay": { enabled: true, config: { relayUrl: "https://mcp.openclaw.ai", agentId: "main" } } } }
Check it works
| Where | What you see |
|---|---|
openclaw mcp-relay status | connected: true, the Gateway ID, the number of grants, "Control UI: available". |
| Connected apps | A row per app: name, access, "Last used …" after the first request. |
openclaw mcp-relay grants | Each grant with who approved it and its access. |
| Your sidebar | A conversation the app started appears like any other. |
Limits
| Limit | Value |
|---|---|
| Message from the app | 8,000 characters |
| Text fields returned | 16,000 characters each, under 512 KiB per response |
| Approvals | A run waiting for your approval shows to the app as running |
| Labels | Messages from an app carry no "MCP Relay" label in the transcript |
| Scope | A grant covers every conversation you can see, not just one |
| Privacy | The relay can read content in transit; it is designed not to store or log it |
| Self-hosting | relayUrl accepts another HTTPS origin, but the relay's code is not in the repository |
If something goes wrong
| You see | What it means | What to do |
|---|---|---|
| "This Gateway requires a person-bound grant. Sign in and pair again from the Connected apps tab." | The Gateway uses trusted-proxy auth, which refuses owner grants. | See On Urbicana today. |
| "Person ingress requires trusted-proxy authentication with verified Cloudflare Access profiles and gateway.roles…" | Person grants need Cloudflare Access. | See On Urbicana today. |
| "Update OpenClaw to enable principal-bound MCP and Control UI access." | The Gateway is too old. | Update OpenClaw. |
| "This connection was revoked. Run openclaw mcp-relay pair and connect again." | The grant was revoked. | Pair the app again. |
| "MCP relay identity is bound to …" | relayUrl was changed after the first connection. | Set it back. |
On Urbicana today
| Step | Today | Why | Fix and cost |
|---|---|---|---|
| Plugin in the image | Yes | The image build leaves out only four other plugins (urbicana-member-base-image.yml:78-81). | None. |
| Stays on after a restart | Yes | The boot merges the member's plugin entries (entrypoint.sh:118-126). | None. |
| Relay socket | Not tried | Outbound only; nothing in the door is involved. | Enable it on one computer and run openclaw mcp-relay status. |
| Pair with code | Refused | The member's Gateway is trusted-proxy, which refuses owner grants (service.ts:213-221). | See the next row. |
| Allow (sign in) | Refused | Person grants need Cloudflare Access headers and gateway.roles (src/gateway/auth.ts:228-242). | A core change that accepts the door's verified member as a person, decided by OpenClaw's security owners; or members who come in through OpenClaw ID (auth.ts:206-209), after its blockers. |
| Stopped computer | Not tried | An app's request reaches the relay, not the door, so it may not wake a stopped computer. | Test once pairing works. |
Videos to record
Record on a Gateway with OpenClaw's default token auth. Owner grants work there.
1 · Switch on MCP Relay
Your Gateway- Plugins → MCP Relay → Enable.
- Terminal:
openclaw mcp-relay status.connected: true. - Pages → Connected apps. "No connected apps yet".
2 · Connect Claude with a code
Your Gateway and Claude- Connected apps → Pair with code → Read and write → Create pairing code. The code and the MCP address.
- In Claude, add a custom connector with
https://mcp.openclaw.ai/mcp. - Enter the code on the relay page and connect.
- Back in OpenClaw, Refresh. A row for Claude, "Read and write", "Not used yet".
3 · Connect ChatGPT by signing in
Your Gateway and ChatGPT- In ChatGPT, add the plugin address.
- On the relay page, Sign in with your Gateway, enter the Control UI address.
- Your Gateway shows "CONNECTION REQUEST · Connect ChatGPT?" and "Returns to chatgpt.com". Allow.
- Open OpenClaw in ChatGPT's sidebar. The full Control UI.
4 · Talk to your agents from Claude
Claude and your Gateway side by side- In Claude: "List my OpenClaw conversations."
- "Start a conversation with my default agent: what can you do?"
- The new conversation appears in OpenClaw's sidebar.
- Connected apps shows "Last used …".
5 · Revoke an app
Your Gateway and Claude- Connected apps → Revoke on Claude's row.
- "Claude revoked. Its MCP and embedded UI access has ended."
- Ask Claude again. "This connection was revoked. Run openclaw mcp-relay pair and connect again."