Skip to main content

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/list within 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 example linear__create_issue), so the normal tools.allow / tools.deny pipeline can filter it.
  • When an agent calls a tool, the plugin evaluates the mcp-operation policy 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

Restart the gateway afterwards. The extension is not enabled by default.

Configuration

Servers live under plugins.entries["mcp-client"].config.servers. Keys are server ids matching ^[a-z0-9][a-z0-9_-]{0,29}$; tools are named after them.
Per server: 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:
Filtering happens before the call: a denied tool is hidden from the model.

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: ask policies 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.json denies every MCP call (reason mcp_policy_unavailable) instead of silently dropping your deny policies; a missing file means no policies.
  • url must 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 failed call.