OpenClaw Core Concepts #9: What Is MCP? The Universal Connector That Turns Your Agent Into a Platform - haiai.world

We’ve spent eight articles building up the full OpenClaw stack from the inside out. You know how the Gateway routes everything, how the Agentic Loop drives execution, how Memory persists knowledge, how the Agent identity shapes behavior, how Tools give the agent capability, how Skills encode how to use those capabilities well, how Sessions hold every conversation together, and how Plugins transplant new organs directly into the Gateway runtime.

Everything so far has described the internal architecture of OpenClaw itself. This article is the first one that looks outward — at the ecosystem OpenClaw connects to.

That outward connection is powered by MCP: the Model Context Protocol.

MCP is the reason your OpenClaw agent can query a Postgres database, manage GitHub issues, read Google Drive files, search Notion, send Slack messages, and talk to hundreds of other services — all without a custom plugin for each one. It’s the standard connector port that plugs OpenClaw into the broader AI tooling world. And now that you understand the full internal stack, you’re in exactly the right position to understand why MCP matters, where it fits in the hierarchy, and how to use it without shooting yourself in the foot.

Quick recap: the full series so far

#	Topic	What it answers
#1	Gateway	What’s the central nervous system?
#2	Agentic Loop	How does the agent actually run?
#3	Memory	How does the agent remember things?
#4	Agent	What is the agent, at its core?
#5	Tools	What can the agent physically do?
#6	Skills	How does the agent know how to do it well?
#7	Sessions	How does the agent track who, where, and what?
#8	Plugins	How do you add new capabilities to the runtime?
#9	MCP	How does OpenClaw connect to the entire external tool ecosystem?

1. What MCP actually is (the two-sentence version)

MCP (Model Context Protocol) is an open standard published by Anthropic, built on JSON-RPC 2.0, that defines how AI agents connect to external tools and data sources through a unified interface. Think of it as USB-C for AI: one protocol that replaces dozens of bespoke integration layers, so that any AI application that speaks MCP can talk to any MCP server — without either side needing to know the other’s implementation details.

Before MCP, connecting an AI agent to a new service meant writing a custom integration: custom auth, custom API calls, custom error handling, custom tool schema — for every single service. MCP replaces all of that with a single standard both sides speak. The server exposes its tools in a structured MCP manifest. The client discovers them, calls them, and gets results — all over a standardized protocol. The integration work drops from days to minutes.

That’s the promise. Now let’s understand how it actually works inside OpenClaw.

2. OpenClaw’s role: the MCP host

In the MCP architecture, there are three distinct roles:

Role	What it is	OpenClaw plays this role?
Host	The AI application that needs external tools	✅ Yes — OpenClaw Gateway is the MCP host
Client	The component inside the host that manages MCP connections	✅ Yes — OpenClaw’s built-in MCP client layer
Server	The external process that exposes tools via MCP	❌ Not by default — external programs you connect to

OpenClaw acts as an MCP host: it initiates connections to MCP servers, discovers the tools they expose, injects those tool schemas into the agent’s context window alongside the built-in tools, and routes tool calls to the appropriate server when the model invokes them. From the agent’s perspective, an MCP-sourced tool is functionally identical to a built-in tool like web_search or fs:write — it shows up in the same tool list, gets called the same way, and returns results in the same format.

This is the architectural elegance of MCP: it extends the tool layer without touching the plugin layer. You don’t need to write a plugin to add a Postgres tool. You connect a Postgres MCP server and the Gateway makes its tools available automatically.

The full call chain looks like this:

text

User message
  → Gateway receives message
  → Context assembled (system prompt + skills + MCP tool schemas injected)
  → Model inference
  → Model decides to call `postgres_query`
  → Gateway routes call to the Postgres MCP server
  → MCP server executes query, returns result
  → Result added to context
  → Next model inference turn
  → Final response streamed to user

The model never knows — or cares — whether postgres_query came from a built-in tool, a plugin, or an MCP server. It just calls it.

3. Three transport types: how OpenClaw talks to MCP servers

MCP servers communicate with the OpenClaw host over one of three transports. Which one you use depends on where the server runs and how you need to connect to it:

3.1 `stdio` (standard input/output)

The simplest and most common transport. OpenClaw spawns the MCP server as a child process and communicates via stdin/stdout pipes. The server starts when the Gateway starts, stays alive for the session, and is killed when the Gateway stops.

JSON

{
  "mcp": {
    "servers": {
      "filesystem": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "./data"]
      },
      "context7": {
        "command": "uvx",
        "args": ["context7-mcp"]
      }
    }
  }
}

Use stdio when: the MCP server is a local process you’re comfortable running as a child of the Gateway. Most community servers ship as stdio by default.

3.2 `sse` (HTTP Server-Sent Events)

Connects to a remote MCP server over HTTP using Server-Sent Events for streaming. The server runs independently — you just point the Gateway at its URL. Sensitive values in url and headers are automatically redacted from logs and status output.

JSON

{
  "mcp": {
    "servers": {
      "remote-tools": {
        "url": "https://mcp.example.com",
        "headers": {
          "Authorization": "Bearer {{env.MCP_TOKEN}}"
        }
      }
    }
  }
}

Use sse when: the MCP server is hosted remotely — either by you (behind a reverse proxy) or by a third-party provider like Composio or Jentic.

3.3 `streamable-http`

An additional transport option alongside stdio and sse. Uses HTTP streaming for bidirectional communication with remote MCP servers, providing more flexible connection semantics than pure SSE for certain server implementations.

JSON

{
  "mcp": {
    "servers": {
      "streaming-tools": {
        "url": "https://mcp.example.com/stream",
        "transport": "streamable-http",
        "connectionTimeoutMs": 30000
      }
    }
  }
}

Use streamable-http when: a remote server specifically requires or recommends it, or when you need configurable connection timeouts for a slow-starting remote service.

Important: when you add or modify MCP server config, restart the Gateway to pick up the changes. openclaw gateway restart does this cleanly. The new tools will appear in the agent’s tool panel after restart.

4. The MCP CLI: managing servers from the command line

OpenClaw ships a full set of openclaw mcp commands for managing your MCP server configuration without hand-editing openclaw.json:

Bash

# List all configured MCP servers and their status
openclaw mcp list

# Show detailed config for a specific server (JSON output)
openclaw mcp show context7 --json

# Add or update an MCP server (stdio)
openclaw mcp set context7 '{"command":"uvx","args":["context7-mcp"]}'

# Add or update an MCP server (SSE remote)
openclaw mcp set docs '{"url":"https://mcp.example.com"}'

# Remove an MCP server
openclaw mcp unset context7

# Test connectivity to a configured server
openclaw mcp test context7

These commands write directly to openclaw.json — mcp set is exactly equivalent to manually adding a block under mcp.servers, but safer (it validates JSON before writing). After any mcp set or mcp unset, restart the Gateway for the change to take effect.

Note what the CLI commands don’t do: they don’t start a live MCP client session, don’t open a channel bridge, and don’t prove a target server is reachable. openclaw mcp test is the verification step — run it after adding a new server to confirm the connection actually works before you rely on it in a production workflow.

5. The MCP bridge: using OpenClaw as an MCP server

There’s a second, distinct use of MCP in OpenClaw that surprises many people when they encounter it: OpenClaw can also act as an MCP server, exposing your agent’s conversations and capabilities to external MCP clients like Claude Code or other AI frameworks.

This is called the MCP bridge. Here’s the setup:

Bash

# Start the MCP bridge (connects to local Gateway over WebSocket)
openclaw mcp

# Enable Claude channel mode (for Claude Code integration)
openclaw mcp --claude-channel-mode on

While the bridge keeps a stdio session open, it:

Connects to your local or remote OpenClaw Gateway over WebSocket
Exposes routed channel conversations over MCP as structured tools
Allows external MCP clients to send messages, read conversation history, poll events, and manage pending approvals

The bridge exposes these tools to generic MCP clients:

conversations_list — list active channel conversations
messages_read — read messages from a specific conversation
events_poll / events_wait — long-poll for new events
messages_send — send a message back through an existing route
approval_list / approval_resolve — inspect and resolve pending exec/plugin approval requests

For Claude Code specifically, enabling --claude-channel-mode on (or leaving the default auto, which behaves the same as on today) adds Claude-specific MCP notifications on top of the standard tools. This lets Claude Code receive live inbound messages as push notifications rather than having to poll — turning OpenClaw into a proper channel adapter for Claude’s native interface.

This is a genuinely powerful pattern: your Claude Code session can delegate tasks to your OpenClaw agent, which then handles everything — including spinning up sub-agents, writing files, and reporting back. Think of it as an AI assistant orchestrating another AI assistant, with MCP as the communication protocol between them.

One important caveat: conversation discovery in the bridge currently depends on existing Gateway session route metadata. A conversation appears in conversations_list only when OpenClaw already has session state with a known route — meaning the channel must have had at least one message exchange. There’s no generic push protocol beyond the Claude-specific adapter yet.

6. MCP vs. Plugins vs. Skills: the definitive three-way comparison

After eight articles, you now have enough context to understand exactly where MCP sits in the extension hierarchy. Here’s the table that settles all three at once:

	Skills	Plugins	MCP
What they are	Markdown playbooks (`SKILL.md`)	TypeScript code modules	External processes (any language)
Where they run	Inside model context window	In-process with the Gateway	As separate processes or remote servers
What they add	Workflow knowledge for existing tools	New tools, channels, providers, hooks	New tools from external services
Can they add new tools?	No	Yes (registered via SDK)	Yes (registered via MCP protocol)
Language	Natural language	TypeScript/JavaScript	Any (TS, Python, Go, Rust…)
Installation	`clawhub install` / local file	`openclaw plugins install`	`openclaw mcp set` / direct config
Security blast radius	Model misled	Gateway process compromised	External process + network access
Best for	Teaching the agent how to work	Extending the runtime itself	Connecting to external APIs and data
Analogy	Textbook	Transplanted organ	Standardized connector port

The mental model: Skills train, Plugins transform, MCP connects.

A practical consequence of this hierarchy: if your use case is “I want my agent to use the GitHub API,” you have three viable paths:

MCP (recommended): configure @modelcontextprotocol/server-github — done in 5 minutes, no code written
Plugin: write a plugin that registers GitHub API calls as new tools via the Plugin SDK — more work, more control
Skill + existing tools: write a SKILL.md that tells the agent to use web_fetch against the GitHub REST API directly — works, but brittle and limited

MCP is the right default for any case where a well-maintained server already exists. Write a plugin only when you need capabilities the MCP protocol can’t support, or when you need the tools deeply integrated into the Gateway lifecycle.

7. Popular MCP servers worth knowing

The MCP ecosystem has grown rapidly. Here’s a practical cross-section of well-maintained servers that work well with OpenClaw:

7.1 Official `@modelcontextprotocol/` servers

Published and maintained by Anthropic. These are the reference implementations:

Package	Transport	What it provides
`@modelcontextprotocol/server-filesystem`	stdio	Read, write, list local files within a specified directory
`@modelcontextprotocol/server-github`	stdio	GitHub repos, issues, PRs, code search
`@modelcontextprotocol/server-postgres`	stdio	Query a Postgres database
`@modelcontextprotocol/server-sqlite`	stdio	Query a local SQLite database
`@modelcontextprotocol/server-brave-search`	stdio	Web search via Brave API
`@modelcontextprotocol/server-puppeteer`	stdio	Browser automation via Puppeteer
`@modelcontextprotocol/server-slack`	stdio	Read messages, post to Slack channels
`@modelcontextprotocol/server-google-drive`	stdio	List, read, create Google Drive files

Install via npx (no global install needed):

JSON

{
  "mcp": {
    "servers": {
      "github": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-github"],
        "env": { "GITHUB_TOKEN": "{{env.GITHUB_TOKEN}}" }
      }
    }
  }
}

7.2 Context7

One of the most useful MCP servers for development workflows. Context7 pulls live, version-specific documentation for popular libraries directly into the agent’s context — eliminating the hallucinated API references that plague AI coding tools.

JSON

{
  "mcp": {
    "servers": {
      "context7": {
        "command": "uvx",
        "args": ["context7-mcp"]
      }
    }
  }
}

Ask your agent: “Using context7, show me the current React 19 API for useOptimistic.” It fetches the actual, current documentation rather than guessing from training data.

7.3 Composio

A hosted MCP aggregator that gives your agent access to 850+ SaaS apps through a single connection — Gmail, GitHub, Notion, Salesforce, Jira, HubSpot, and many more — handling all OAuth flows automatically. Rather than configuring individual MCP servers for each app, Composio’s Tool Router dynamically loads tools for whatever service the current task requires.

JSON

{
  "mcp": {
    "servers": {
      "composio": {
        "url": "https://connect.composio.dev/mcp",
        "headers": {
          "Authorization": "Bearer {{env.COMPOSIO_API_KEY}}"
        }
      }
    }
  }
}

If a tool returns an auth error, the agent will prompt you to connect that toolkit at the Composio dashboard. From that point on, it handles token refresh and revocation automatically.

7.4 Pieces Long-Term Memory

Connects OpenClaw to the Pieces Long-Term Memory Engine (LTM-2.7), giving the agent access to your complete work history — code snippets, documents, past conversations, and workstream activity — beyond what OpenClaw’s own Memory system stores. The agent can autonomously query your past work, generate standups, monitor recent activity, and surface relevant context without you asking. PiecesOS must be running locally (port 39300–39333) for this to work.

7.5 Jentic

A managed MCP server that provides access to 200+ external APIs through a centralized, session-authenticated interface. Instead of embedding API keys per-tool in your OpenClaw config, Jentic manages all credentials on its platform. The workflow: search_apis to find operations → load_execution_info to get parameters → execute to run. All operations are audit-logged through Jentic, which is useful for compliance-sensitive deployments.

8. The MCP skill pattern: ClawHub as the MCP onboarding layer

There’s a pattern worth calling out explicitly: many MCP integrations on ClawHub are published not as raw openclaw.json configs, but as Skills that handle the MCP setup and tool registration for you.

This is intentional. A skill can:

Document the correct MCP server config for a specific service
Tell the agent how to use the MCP tools once they’re connected
Provide fallback instructions when the server is unreachable
Encode service-specific quirks that the MCP server alone doesn’t capture

The Pieces integration is a good example: the ClawHub skill jackrosspieces/pieces-mcp handles the full setup — MCP-only URLs, tunnel configuration when PiecesOS runs on a different machine, mcporter.json, mcp-remote setup, and gateway restart sequence. The skill is the documentation and the workflow guide, and the MCP connection is the capability layer underneath it.

This means that for many popular MCP integrations, the fastest path is:

Bash

# Search for the skill on ClawHub
openclaw skills search "pieces long-term memory"

# Install the skill — it includes the MCP config instructions
openclaw skills install jackrosspieces/pieces-mcp

The skill installs and gives the agent the workflow knowledge. You follow its configuration steps to wire up the MCP server. After a Gateway restart, both layers are active.

9. Environment variables in MCP config: the right way to handle secrets

MCP servers frequently need API keys, tokens, or database credentials. These should never be hardcoded into openclaw.json. The correct pattern uses the {{env.VAR_NAME}} template syntax, which OpenClaw resolves from environment variables at Gateway startup:

JSON

{
  "mcp": {
    "servers": {
      "github": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-github"],
        "env": {
          "GITHUB_TOKEN": "{{env.GITHUB_TOKEN}}"
        }
      },
      "remote-analytics": {
        "url": "https://analytics.internal/mcp",
        "headers": {
          "Authorization": "Bearer {{env.ANALYTICS_TOKEN}}"
        }
      }
    }
  }
}

Set the actual values in your shell environment or a .env file that your Gateway daemon sources at startup. The OpenClaw Gateway redacts sensitive values from url (userinfo) and headers in all logs and status output — so even if you run openclaw mcp list --json, tokens are masked. But they’re still plaintext in openclaw.json if you don’t use the template syntax. Use the template.

10. Security: MCP is a real attack surface

MCP extends what your agent can reach — and every thing it can reach is also something that can be abused. The security considerations here are distinct from those of Plugins but equally important.

The threat model

MCP servers run with Gateway permissions. A stdio MCP server is a child process of the Gateway. It inherits the Gateway’s OS user permissions and can access anything that user can access — unless explicitly sandboxed. A malicious or compromised MCP server can read files outside its intended scope, make outbound network calls, or exfiltrate data through its tool return values.

Prompt injection via tool results. An MCP server that returns attacker-controlled content — a webpage, a database row, a file — can embed instructions that the model interprets as legitimate commands. This is the same prompt injection risk discussed in Skills security, but now it arrives through a tool result rather than a Markdown file.

Remote server trust. SSE and streamable-http transports connect to remote servers over the network. If that remote server is compromised, your agent starts receiving tool results from an attacker. A server that initially passed review can become malicious after a silent update.

Credential exposure. MCP servers in the env block receive whatever API keys and tokens you pass them. A compromised server can exfiltrate those credentials through log output, outbound requests, or error messages that get included in the model’s context.

Your non-negotiable checklist before enabling any MCP server

For stdio servers: read the source. Most community MCP servers are open source. Before you npx -y anything, look at what that package actually does. A server that needs filesystem access for a database tool is suspicious.
Scope filesystem MCP servers tightly. @modelcontextprotocol/server-filesystem takes a directory argument — always pass the narrowest directory you can get away with, not ./ or ~. The principle of least privilege applies to MCP servers just as it does to Tool permissions.
Use scoped tokens for API-connected servers. The GitHub token you pass to an MCP server should have only the permissions that server legitimately needs — read-only for a search server, not full repo write access.
Don’t expose sensitive MCP servers publicly. If your Gateway runs in remote mode behind a reverse proxy, your MCP servers are internal to that machine. Don’t inadvertently expose MCP server ports to the public internet.
Review MCP server access logs periodically. Servers like Jentic provide audit logs for all operations. Use them. Unexpected API calls from your agent are often the first sign of a prompt injection attack.
Keep servers updated. MCP servers are actively maintained packages. Run npm update on your local servers and watch for security advisories from the publishers of remote services you use.
Test connectivity explicitly. Run openclaw mcp test <server-name> after any server update or config change. A server that was working may fail silently after an upstream change — and a silently-failing tool causes the model to hallucinate results rather than reporting an error.

11. Troubleshooting: the five most common MCP problems

Problem	Likely cause	Fix
Tools don’t appear after config	Gateway not restarted after `mcp set`	`openclaw gateway restart`
`openclaw mcp test` fails	Server not installed, or wrong command path	`npx -y <package>` to install, then test again
`invalid_request` from model	Tool schema has a type mismatch	Run `openclaw mcp show <name> --json` and check the schema
Auth error from SSE server	Token expired or `{{env.VAR}}` not resolving	Check env variable is exported before Gateway starts
stdio server exits immediately	Missing dependency or wrong args	Run the command manually in a terminal to see the error

A general-purpose debug workflow:

Bash

# 1. Check what the Gateway sees
openclaw mcp list --json

# 2. Verify the server is configured correctly
openclaw mcp show my-server --json

# 3. Test connectivity
openclaw mcp test my-server

# 4. If still broken, run the server command manually
npx -y @modelcontextprotocol/server-github
# → Look at the error output directly

# 5. Check Gateway logs for MCP-related errors
openclaw logs --filter mcp

12. End-to-end example: three MCP servers, one agent, one task

Let’s trace exactly what happens when your agent uses MCP servers to handle a real task.

Setup — three servers configured in openclaw.json:

JSON

{
  "mcp": {
    "servers": {
      "github": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-github"],
        "env": { "GITHUB_TOKEN": "{{env.GITHUB_TOKEN}}" }
      },
      "context7": {
        "command": "uvx",
        "args": ["context7-mcp"]
      },
      "filesystem": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "./reports"]
      }
    }
  }
}

You type: "Find all open issues labeled 'bug' in my backend repo, look up the relevant API docs for the modules involved, and write a prioritized bug report to reports/bugs-this-week.md"

What happens at the MCP layer:

Gateway starts session → all three MCP server tool schemas injected into context alongside built-in tools → agent sees github_list_issues, github_get_issue, context7_get_docs, filesystem_write, and all other available tools
First tool call → model calls github_list_issues with labels: ["bug"], state: "open" → Gateway routes to the GitHub MCP server → server calls GitHub API → returns list of 7 open bugs
Second tool calls (parallel) → model calls github_get_issue for each bug to get detail → 7 calls, 7 results
Third tool calls → model identifies 3 modules mentioned across the bugs → calls context7_get_docs for each → live documentation retrieved from the Context7 server
Fourth tool call → model composes the prioritized report with real API context → calls filesystem_write to reports/bugs-this-week.md → report written to disk
Response streamed → “I’ve written a prioritized bug report to reports/bugs-this-week.md with 7 bugs across 3 modules, sorted by severity…”

Three MCP servers, zero custom plugins, zero new code. The entire integration layer is configuration — and it took less than 10 minutes to set up. That’s what MCP delivers.

The three-sentence summary

MCP (Model Context Protocol) is an open JSON-RPC 2.0 standard that lets OpenClaw — acting as an MCP host — connect to external tool servers via stdio, sse, or streamable-http transports, automatically injecting those servers’ tools into the agent’s context alongside built-in tools and plugin-registered tools. From the model’s perspective there is no difference between a built-in web_search and an MCP-sourced github_list_issues — they’re both just callable tools with typed schemas. MCP is the extension path of first resort for connecting to external services: use it before reaching for a plugin, configure servers tightly with scoped credentials and narrow filesystem access, restart the Gateway after every config change, and always verify connectivity with openclaw mcp test before you depend on a server in production.

What’s next

We’ve now covered nine core concepts — the full internal stack plus the external connectivity layer. In #10, we’ll zoom out to look at multi-agent architectures: how multiple OpenClaw agents cooperate on complex tasks, how the Sessions and messaging tools from earlier in this series combine with specialized agents and MCP connections to build systems that are genuinely more capable than any single agent running alone.

References

OpenClaw Official Docs — MCP CLI Reference https://docs.openclaw.ai/cli/mcp
OpenClaw Official Docs — Tools Overview https://docs.openclaw.ai/tools
OpenClaw Official Docs — Community Plugins (MCP Ecosystem) https://docs.openclaw.ai/tools/community-plugins
openclawcenter.com — OpenClaw MCP: Model Context Protocol https://www.openclawcenter.com/docs/mcp
openclaw-ai.com — OpenClaw Docs (Concepts Index) https://openclaw-ai.com/en/docs
openclawcn.com — OpenClaw Documentation https://openclawcn.com/en/docs/
GitHub — freema/openclaw-mcp (OpenClaw MCP Bridge) https://github.com/freema/openclaw-mcp