MCP Client plugin
mcp-client is a bundled, disabled-by-default extension that connects MCP servers you configure
and exposes each server tool to agents as a regular tool. Every call passes the canonical
mcp-operation policy check (deny-first, ADR 0307) and writes exactly one redacted audit row to a
plugin-owned mcp_call_events table on SQLite or Postgres.
Two transports are supported: stdio (the gateway spawns the server process) and
streamable-http (the gateway calls a Streamable HTTP endpoint). There is no SSE transport and no
OAuth; remote servers authenticate with static headers whose values come from secret references,
never from plaintext config.
What it does
- At gateway start, the plugin service connects every enabled configured server and lists its
tools. A server that fails to connect or answer
tools/listwithin 10 seconds logs a warning and is skipped; one bad server never blocks the others. - Each listed tool becomes an agent tool named
<serverId>__<tool>(for examplelinear__create_issue), so the normaltools.allow/tools.denypipeline can filter it. - When an agent calls a tool, the plugin evaluates the
mcp-operationpolicy request. On allow it calls the server, on deny it refuses without contacting the server, and either way it writes one audit row. - Tools appear on gateway turns only after the service has started. A server config change takes effect when the gateway restarts the plugin service; a running turn is never interrupted.
Enable the plugin
Configuration
Servers live underplugins.entries["mcp-client"].config.servers. Keys are server ids matching
^[a-z0-9][a-z0-9_-]{0,29}$; tools are named after them.
stdio and streamable-http fields are mutually exclusive: a stdio server refuses url and
headers, and a streamable-http server refuses command, args, env and cwd.
Stdio servers only start when the gateway runs in role all (a home lab or single host). Any
other deployment role refuses them with a warning, because a spawned child process is host-local
and cannot be reproduced across replicas. The stderr of a stdio server is never copied into logs.
Tool names and filtering
A tool is named<serverId>__<safeTool>. safeTool replaces every character outside
[A-Za-z0-9_-] with _, and the full name is capped at 64 characters. If two tools would get the
same name (compared case-insensitively), the later one gets a -2, -3, … suffix. Names are
stable: they are assigned in config order and do not change when a server is relisted.
Filter with the ordinary tool policy knobs, on the full tool name, on the plugin id, or on the
plugin group:
Policies
Beyond tool filtering, every call is checked against the ADR 0307 policy engine. Policies come from~/.openclaw/exec-approvals.json (v2). Without any policy the default is allow, because
you configured the server. deny wins over ask and allow; ask is treated as deny with the
reason mcp_approval_unavailable, because there is no interactive approval UI in this release.
match accepts mcpServerId, mcpToolName and operationClass (read, write or
destructive, derived from the server’s tool annotations: destructiveHint means destructive,
otherwise readOnlyHint means read, everything else is write). Every decision, allow or deny,
also lands in the exec audit log.
operationClass is what the server says about its tools; nothing verifies it. For a server you
do not fully trust, write policies on mcpServerId and mcpToolName rather than on
operationClass.
The audit table
Exactly one row is written per tool call, whatever the outcome. Columns:event_id (primary key),
created_at_ms, agent_id, session_key, session_id, run_id, turn_id, tool_call_id,
server_id, transport, tool_name (the raw name, not the display name), operation_class,
decision, policy_effect, policy_id, reason, outcome (ok, tool_error, denied or
failed), error_code, latency_ms, args_summary_json, result_summary_json and
policy_request_json.
Argument and result values are never stored. Each summary carries a sha256 over the canonical
JSON, the byte size, and the argument key names plus their JSON types. policy_request_json
stores the full canonical policy request, so an audit row explains exactly what was evaluated.
Where the table lives:
Override the SQLite file with
config.storage.sqlitePath, or select Postgres with
config.storage.backend: "postgres" (plus databaseUrl and schema overrides). If the store
cannot be opened or migrated at startup, the plugin logs
call audit store unavailable; MCP tools disabled and exposes no MCP tools: a call that cannot be
audited does not happen.
Limits
- No OAuth and no per-user tokens: remote servers authenticate with SecretRef headers only. OAuth for remote servers and per-user credentials are later work.
- No SSE transport; Streamable HTTP only.
- No interactive approvals:
askpolicies deny the call. - Stdio servers are refused outside deployment role
all. - ACP clients cannot supply MCP servers; they are ignored with a log line naming the reason.
- No SSRF guard on
url: operator config is trusted. Guards arrive together with user-owned servers. - No rate limits or metering yet.
- Tools appear only on gateway turns after the plugin service has started.
- A corrupt or malformed
exec-approvals.jsondenies every MCP call (reasonmcp_policy_unavailable) instead of silently dropping your deny policies; a missing file means no policies. urlmust not embed credentials (https://user:pass@...is rejected); use SecretRef headers.- Server-supplied tool metadata is treated as untrusted: descriptions are stripped of control characters and capped at 2048 characters, and tools with names over 256 characters or input schemas over 64 KiB are skipped with a warning.
- If a server’s connection drops, its tools stay listed and the next call reconnects once; a failed
reconnect is recorded as a
failedcall.