MCP

openclaw mcp heeft twee taken:

• OpenClaw uitvoeren als MCP-server met openclaw mcp serve
• door OpenClaw beheerde uitgaande MCP-serverdefinities beheren met list, show, status, doctor, probe, add, set, configure, tools, login, logout, reload en unset

Met andere woorden:

• serve is OpenClaw dat optreedt als MCP-server
• de andere subcommando's zijn OpenClaw dat optreedt als MCP-clientzijdig register voor MCP-servers die zijn runtimes later kunnen gebruiken

Gebruik openclaw acp wanneer OpenClaw zelf een coderingsharness-sessie moet hosten en die runtime via ACP moet routeren.

Kies het juiste MCP-pad

OpenClaw heeft meerdere MCP-oppervlakken. Kies het oppervlak dat past bij wie eigenaar is van de agentruntime en wie eigenaar is van de tools.

OpenClaw als MCP-server

Dit is het pad openclaw mcp serve.

Wanneer serve gebruiken

Gebruik openclaw mcp serve wanneer:

• Codex, Claude Code of een andere MCP-client rechtstreeks moet praten met door OpenClaw ondersteunde kanaalgesprekken
• je al een lokale of externe OpenClaw Gateway hebt met gerouteerde sessies
• je één MCP-server wilt die werkt met alle kanaalbackends van OpenClaw in plaats van afzonderlijke bridges per kanaal uit te voeren

Gebruik in plaats daarvan openclaw acp wanneer OpenClaw zelf de coderingsruntime moet hosten en de agentsessie binnen OpenClaw moet houden.

Hoe het werkt

openclaw mcp serve start een stdio-MCP-server. De MCP-client is eigenaar van dat proces. Zolang de client de stdio-sessie openhoudt, maakt de bridge verbinding met een lokale of externe OpenClaw Gateway via WebSocket en stelt gerouteerde kanaalgesprekken beschikbaar via MCP.

Kies een clientmodus

Gebruik dezelfde bridge op twee verschillende manieren:

Wat serve beschikbaar stelt

De bridge gebruikt bestaande Gateway-sessieroutemetadata om door kanalen ondersteunde gesprekken beschikbaar te stellen. Een gesprek verschijnt wanneer OpenClaw al sessiestatus heeft met een bekende route, zoals:

• channel
• ontvanger- of bestemmingsmetadata
• optionele accountId
• optionele threadId

Dit geeft MCP-clients één plek om:

• recente gerouteerde gesprekken te vermelden
• recente transcriptgeschiedenis te lezen
• te wachten op nieuwe inkomende gebeurtenissen
• een antwoord terug te sturen via dezelfde route
• goedkeuringsverzoeken te zien die aankomen terwijl de bridge verbonden is

Gebruik

openclaw mcp serve

openclaw mcp serve --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

openclaw mcp serve --url wss://gateway-host:18789 --password-file ~/.openclaw/gateway.password

openclaw mcp serve --verboseopenclaw mcp serve --claude-channel-mode off

Bridge-tools

De huidige bridge stelt deze MCP-tools beschikbaar:

Gebeurtenismodel

De bridge houdt een in-memory gebeurteniswachtrij bij terwijl hij verbonden is.

Huidige gebeurtenistypen:

• message
• exec_approval_requested
• exec_approval_resolved
• plugin_approval_requested
• plugin_approval_resolved
• claude_permission_request

Claude-kanaalmeldingen

De bridge kan ook Claude-specifieke kanaalmeldingen beschikbaar stellen. Dit is het OpenClaw-equivalent van een Claude Code-kanaaladapter: standaard MCP-tools blijven beschikbaar, maar live inkomende berichten kunnen ook aankomen als Claude-specifieke MCP-meldingen.

Wanneer Claude-kanaalmodus is ingeschakeld, adverteert de server Claude-experimentele mogelijkheden en kan hij het volgende uitzenden:

• notifications/claude/channel
• notifications/claude/channel/permission

Huidig bridgegedrag:

• inkomende user-transcriptberichten worden doorgestuurd als notifications/claude/channel
• Claude-toestemmingsverzoeken die via MCP worden ontvangen, worden in-memory bijgehouden
• als de opdrachteigenaar in het gekoppelde gesprek later yes abcde of no abcde verzendt, zet de bridge dat om naar notifications/claude/channel/permission
• deze meldingen zijn alleen voor de live-sessie; als de MCP-client de verbinding verbreekt, is er geen pushdoel

Dit is bewust clientspecifiek. Generieke MCP-clients moeten vertrouwen op de standaard pollingtools.

MCP-clientconfiguratie

Voorbeeld van stdio-clientconfiguratie:

{  "mcpServers": {    "openclaw": {      "command": "openclaw",      "args": [        "mcp",        "serve",        "--url",        "wss://gateway-host:18789",        "--token-file",        "/path/to/gateway.token"      ]    }  }}

Begin voor de meeste generieke MCP-clients met het standaard tooloppervlak en negeer Claude-modus. Schakel Claude-modus alleen in voor clients die de Claude-specifieke meldingsmethoden daadwerkelijk begrijpen.

Opties

openclaw mcp serve ondersteunt:

Beveiliging en vertrouwensgrens

De bridge verzint geen routering. Deze stelt alleen gesprekken beschikbaar waarvan Gateway al weet hoe die moeten worden gerouteerd.

Dat betekent:

• allowlists voor afzenders, koppeling en vertrouwen op kanaalniveau blijven bij de onderliggende OpenClaw-kanaalconfiguratie horen
• messages_send kan alleen antwoorden via een bestaande opgeslagen route
• goedkeuringsstatus is alleen live/in-memory voor de huidige bridgesessie
• bridge-authenticatie moet dezelfde Gateway-token- of wachtwoordcontroles gebruiken die je zou vertrouwen voor elke andere externe Gateway-client

Als een gesprek ontbreekt in conversations_list, is MCP-configuratie meestal niet de oorzaak. De oorzaak is ontbrekende of onvolledige routemetadata in de onderliggende Gateway-sessie.

Testen

OpenClaw levert een deterministische Docker-smoke voor deze bridge:

pnpm test:docker:mcp-channels

Die smoke:

• start een vooraf gevulde Gateway-container
• start een tweede container die openclaw mcp serve start
• verifieert gespreksdetectie, transcriptlezingen, lezingen van bijlagemetadata, gedrag van de live eventwachtrij en routering van uitgaande verzending
• valideert Claude-achtige kanaal- en machtigingsmeldingen via de echte stdio MCP-bridge

Dit is de snelste manier om te bewijzen dat de bridge werkt zonder een echt Telegram-, Discord- of iMessage-account aan de testrun te koppelen.

Zie Testen voor bredere testcontext.

Probleemoplossing

OpenClaw als MCP-clientregister

Dit is het pad voor openclaw mcp list, show, status, doctor, probe, add, set, configure, tools, login, logout, reload en unset.

Deze opdrachten stellen OpenClaw niet beschikbaar via MCP. Ze beheren door OpenClaw beheerde MCP-serverdefinities onder mcp.servers in de OpenClaw-configuratie. Ze lezen geen mcporter-servers uit config/mcporter.json.

Die opgeslagen definities zijn bedoeld voor runtimes die OpenClaw later start of configureert, zoals embedded OpenClaw en andere runtime-adapters. OpenClaw slaat de definities centraal op zodat die runtimes hun eigen dubbele MCP-serverlijsten niet hoeven bij te houden.

Runtime-adapters kunnen dit gedeelde register normaliseren naar de vorm die hun downstream-client verwacht. Embedded OpenClaw gebruikt bijvoorbeeld OpenClaw-transport-waarden rechtstreeks, terwijl Claude Code en Gemini CLI-native type-waarden ontvangen zoals http, sse of stdio.

Codex app-server respecteert ook een optioneel codex-blok op elke server. Dit is OpenClaw-projectiemetadata alleen voor Codex app-server-threads; het wijzigt geen ACP-sessies, generieke Codex-harnessconfiguratie of andere runtime-adapters. Gebruik niet-lege codex.agents om een server alleen naar specifieke OpenClaw- agent-id's te projecteren. Lege, blanco of ongeldige agentlijsten worden door configuratievalidatie geweigerd en door het runtime-projectiepad weggelaten in plaats van globaal te worden. Gebruik codex.defaultToolsApprovalMode (auto, prompt of approve) om Codex' native default_tools_approval_mode voor een vertrouwde server uit te geven. OpenClaw verwijdert de codex-metadata voordat de native mcp_servers- configuratie aan Codex wordt doorgegeven.

Opgeslagen MCP-serverdefinities

OpenClaw slaat ook een lichtgewicht MCP-serverregister op in de configuratie voor oppervlakken die door OpenClaw beheerde MCP-definities willen.

Opdrachten:

• openclaw mcp list
• openclaw mcp show [name]
• openclaw mcp status [--verbose]
• openclaw mcp doctor [name] [--probe]
• openclaw mcp probe [name]
• openclaw mcp add <name> [flags]
• openclaw mcp set <name> <json>
• openclaw mcp configure <name> [flags]
• openclaw mcp tools <name> [--include csv] [--exclude csv] [--clear]
• openclaw mcp login <name> [--code code]
• openclaw mcp logout <name>
• openclaw mcp reload
• openclaw mcp unset <name>

Opmerkingen:

• list sorteert servernamen.
• show zonder naam drukt het volledige geconfigureerde MCP-serverobject af.
• status classificeert geconfigureerde transporten zonder verbinding te maken. --verbose bevat opgeloste details over starten, timeout, OAuth, filter en parallelle aanroepen.
• doctor voert statische controles uit zonder verbinding te maken. Voeg --probe toe wanneer de opdracht ook moet verifiëren dat ingeschakelde servers verbinding maken.
• probe maakt verbinding en rapporteert toollaantallen, ondersteuning voor resources/prompts, ondersteuning voor lijstwijzigingen en diagnostiek.
• add accepteert stdio-flags zoals --command, --arg, --env en --cwd, of HTTP-flags zoals --url, --transport, --header, --auth oauth, TLS, timeout en toolselectieflags.
• set verwacht één JSON-objectwaarde op de opdrachtregel.
• configure werkt inschakeling, toolfilters, time-outs, OAuth, TLS en hints voor parallelle toolaanroepen bij zonder de volledige serverdefinitie te vervangen.
• tools werkt toolfilters per server bij. Include/exclude-items zijn MCP-toolnamen en eenvoudige *-globs.
• login voert de OAuth-flow uit voor HTTP-servers die zijn geconfigureerd met auth: "oauth". De eerste run drukt een autorisatie-URL af; voer opnieuw uit met --code na goedkeuring.
• logout wist opgeslagen OAuth-referenties voor de genoemde server zonder de opgeslagen serverdefinitie te verwijderen.
• reload verwijdert gecachte in-process MCP-runtimes. Gateway- of agentprocessen in een ander proces hebben nog steeds hun eigen reload- of herstartpad nodig.
• Gebruik transport: "streamable-http" voor Streamable HTTP MCP-servers. openclaw mcp set normaliseert ook CLI-native type: "http" naar dezelfde canonieke configuratievorm voor compatibiliteit.
• unset mislukt als de genoemde server niet bestaat.

Voorbeelden:

openclaw mcp listopenclaw mcp show context7 --jsonopenclaw mcp status --verboseopenclaw mcp doctor --probeopenclaw mcp probe context7 --jsonopenclaw mcp add memory --command npx --arg -y --arg @modelcontextprotocol/server-memoryopenclaw mcp set context7 '{"command":"uvx","args":["context7-mcp"]}'openclaw mcp tools context7 --include 'resolve-library-id,get-library-docs'openclaw mcp set docs '{"url":"https://mcp.example.com","transport":"streamable-http"}'openclaw mcp configure docs --timeout 20 --connect-timeout 5 --include 'search,read_*'openclaw mcp configure docs --auth oauth --oauth-scope 'docs.read'openclaw mcp login docsopenclaw mcp logout docsopenclaw mcp unset context7

Veelgebruikte serverrecepten

Deze voorbeelden slaan alleen serverdefinities op. Voer daarna openclaw mcp doctor --probe uit om te bewijzen dat de server start en tools beschikbaar stelt.

openclaw mcp add files \  --command npx \  --arg -y \  --arg @modelcontextprotocol/server-filesystem \  --arg "$HOME/Documents" \  --include 'read_file,list_directory,search_files'openclaw mcp doctor files --probe

openclaw mcp add memory \  --command npx \  --arg -y \  --arg @modelcontextprotocol/server-memoryopenclaw mcp probe memory --json

openclaw mcp add local-tools \  --command node \  --arg ./dist/mcp-server.js \  --cwd /srv/openclaw-tools \  --env API_BASE=https://internal.exampleopenclaw mcp status --verbose

openclaw mcp add docs \  --url https://mcp.example.com/mcp \  --transport streamable-http \  --auth oauth \  --oauth-scope docs.read \  --timeout 20 \  --connect-timeout 5 \  --include 'search,read_*'openclaw mcp doctor docs --probe

openclaw mcp set cua-driver '{"command":"cua-driver","args":["mcp"]}'openclaw mcp tools cua-driver --include 'list_apps,observe,click,type'openclaw mcp doctor cua-driver --probe

JSON-uitvoervormen

Gebruik --json voor scripts en dashboards. Veldsets kunnen in de loop van de tijd groeien, dus consumers moeten onbekende sleutels negeren.

{  "path": "/home/user/.openclaw/openclaw.json",  "servers": [    {      "name": "docs",      "configured": true,      "enabled": true,      "ok": true,      "transport": "streamable-http",      "launch": "streamable-http https://mcp.example.com/mcp",      "auth": "oauth",      "authStatus": {        "hasTokens": true,        "hasClientInformation": true,        "hasCodeVerifier": false,        "hasDiscoveryState": true,        "hasLastAuthorizationUrl": false      },      "requestTimeoutMs": 20000,      "connectionTimeoutMs": 5000,      "toolFilter": {        "include": ["search", "read_*"],        "exclude": []      },      "supportsParallelToolCalls": true    }  ]}

{  "ok": false,  "path": "/home/user/.openclaw/openclaw.json",  "servers": [    {      "name": "docs",      "ok": false,      "issues": [        {          "level": "error",          "message": "OAuth credentials are not authorized; run openclaw mcp login docs"        }      ]    }  ]}

{  "path": "/home/user/.openclaw/openclaw.json",  "generatedAt": "2026-05-31T09:00:00.000Z",  "servers": {    "docs": {      "launch": "streamable-http https://mcp.example.com/mcp",      "tools": 2,      "resources": true,      "prompts": false,      "listChanged": {        "tools": true,        "resources": false,        "prompts": false      }    }  },  "tools": ["docs__read_page", "docs__search"],  "diagnostics": []}

Voorbeeld van configuratievorm:

{  "mcp": {    "servers": {      "context7": {        "command": "uvx",        "args": ["context7-mcp"]      },      "docs": {        "url": "https://mcp.example.com",        "transport": "streamable-http",        "timeout": 20,        "connectTimeout": 5,        "supportsParallelToolCalls": true,        "auth": "oauth",        "oauth": {          "scope": "docs.read"        },        "sslVerify": true,        "clientCert": "/path/to/client.crt",        "clientKey": "/path/to/client.key",        "toolFilter": {          "include": ["search_*"],          "exclude": ["admin_*"]        }      }    }  }}

Stdio-transport

Start een lokaal childproces en communiceert via stdin/stdout.

SSE / HTTP-transport

Maakt verbinding met een externe MCP-server via HTTP Server-Sent Events.

Voorbeeld:

{  "mcp": {    "servers": {      "remote-tools": {        "url": "https://mcp.example.com",        "auth": "oauth",        "timeout": 20,        "headers": {          "Authorization": "Bearer <token>"        }      }    }  }}

Gevoelige waarden in url (userinfo) en headers worden geredigeerd in logs en statusuitvoer. openclaw mcp doctor waarschuwt wanneer gevoelig lijkende headers- of env-items letterlijke waarden bevatten, zodat operators die waarden uit gecommitte configuratie kunnen verplaatsen.

OAuth-workflow

OAuth is bedoeld voor HTTP MCP-servers die de MCP OAuth-flow adverteren. Statische Authorization-headers worden voor een server genegeerd zolang auth: "oauth" is ingeschakeld.

openclaw mcp set docs '{"url":"https://mcp.example.com/mcp","transport":"streamable-http","auth":"oauth","oauth":{"scope":"docs.read"}}'

openclaw mcp login docs

openclaw mcp login docs --code abc123

openclaw mcp status --verboseopenclaw mcp doctor docs --probe

openclaw mcp logout docs

Als de provider tokens roteert of de autorisatiestatus vastloopt, voer dan openclaw mcp logout <name> uit en herhaal daarna login. logout kan credentials voor een opgeslagen HTTP-server wissen, zelfs nadat auth: "oauth" uit de configuratie is verwijderd, zolang de servernaam en URL de vermelding in de credentialstore nog identificeren.

Streamable HTTP-transport

streamable-http is een extra transportoptie naast sse en stdio. Het gebruikt HTTP-streaming voor bidirectionele communicatie met externe MCP-servers.

OpenClaw-configuratie gebruikt transport: "streamable-http" als de canonieke spelling. CLI-native MCP-waarden type: "http" worden geaccepteerd wanneer ze via openclaw mcp set worden opgeslagen en door openclaw doctor --fix in bestaande configuratie worden gerepareerd, maar transport is wat embedded OpenClaw direct consumeert.

Voorbeeld:

{  "mcp": {    "servers": {      "streaming-tools": {        "url": "https://mcp.example.com/stream",        "transport": "streamable-http",        "connectTimeout": 10,        "timeout": 30,        "headers": {          "Authorization": "Bearer <token>"        }      }    }  }}

Control UI

De browser-Control UI bevat een speciale MCP-instellingenpagina op /mcp. Deze toont aantallen geconfigureerde servers, samenvattingen van ingeschakeld/OAuth/filter, transportrijen per server, besturingselementen voor inschakelen/uitschakelen, gangbare CLI-opdrachten en een scoped editor voor de configuratiesectie mcp.

Gebruik de pagina voor operatorbewerkingen en snelle inventarisatie. Gebruik openclaw mcp doctor --probe of openclaw mcp probe wanneer je live serverbewijs nodig hebt.

Operatorworkflow:

1. Open de Control-UI en kies MCP.
2. Bekijk de overzichtskaarten voor totale, ingeschakelde, OAuth- en gefilterde servers.
3. Gebruik elke serverrij voor hints over transport, auth, filter, timeout en opdracht.
4. Schakel inschakeling om wanneer je een definitie wilt behouden maar deze wilt uitsluiten van runtime-detectie.
5. Bewerk de scoped mcp-configsectie voor structurele wijzigingen zoals nieuwe servers, headers, TLS, OAuth-metadata of toolfilters.
6. Kies Opslaan om alleen de config te bewaren, of Opslaan en publiceren om deze via het Gateway-configpad toe te passen.
7. Voer openclaw mcp doctor --probe uit wanneer je live bewijs nodig hebt dat de bewerkte server start en tools weergeeft.

Notities:

• opdrachtsnippets zetten servernamen tussen aanhalingstekens zodat ongebruikelijke namen kopieerbaar blijven in een shell
• weergegeven URL-achtige waarden worden vóór rendering geredigeerd wanneer ze ingesloten referenties bevatten
• de pagina start MCP-transports niet zelf
• actieve runtimes kunnen openclaw mcp reload, publiceren van Gateway-config of een procesherstart nodig hebben, afhankelijk van welk proces de MCP-clients bezit

Huidige limieten

Deze pagina documenteert de bridge zoals die vandaag wordt geleverd.

Huidige limieten:

• gespreksdetectie is afhankelijk van bestaande metagegevens van Gateway-sessieroutes
• geen generiek pushprotocol buiten de Claude-specifieke adapter
• nog geen tools voor het bewerken van berichten of reageren
• HTTP/SSE/streamable-http-transport maakt verbinding met één externe server; nog geen gemultiplexte upstream
• permissions_list_open bevat alleen goedkeuringen die zijn waargenomen terwijl de bridge verbonden is

Gerelateerd

• CLI-referentie
• Plugins