What Is MCP and Why Your Agent Needs It
Model Context Protocol (MCP) is an open standard created by Anthropic in late 2024 and donated to the Linux Foundation in December 2025. It defines a universal way for AI agents to discover and call external tools. Before MCP, every tool integration was custom glue code. MCP replaces all of that with a single protocol that works across OpenClaw, Claude Code, Cursor, Windsurf, and every major AI coding tool.
According to the MCP project maintainers, the combined Python and TypeScript SDKs crossed 97 million monthly downloads by February 2026. The ecosystem has exploded -- over 10,000 community-built MCP servers exist on GitHub, covering everything from Stripe payments to Kubernetes management.
Without MCP
Custom API wrappers per tool. Brittle integrations. Each tool requires its own auth flow, error handling, and schema definition. Adding a new tool means writing and maintaining more code.
With MCP
One protocol, any tool. Add a server entry to your config and restart. The agent discovers tools automatically. Swap servers without changing agent code. Community servers cover most common integrations.
How to Add an MCP Server to OpenClaw
OpenClaw supports two methods for adding MCP servers: the CLI command and direct config editing. The CLI is faster for simple servers. Direct config editing gives you full control over environment variables, args, and transport settings.
Method 1: CLI Command
The fastest way to register a server. One command, one restart, and the agent has new tools.
# Add a stdio server (local process)
openclaw mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /path/to/allowed/dir
# Add an HTTP server (remote service)
openclaw mcp add my-api --transport http https://mcp.example.com/sseMethod 2: Direct Config Editing
For complex setups with environment variables, edit ~/.openclaw/openclaw.json directly. This is the method we use in production because it keeps all server configs in one auditable file.
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
}
},
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/Users/you/projects"
]
},
"postgres": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres"],
"env": {
"DATABASE_URL": "${DATABASE_URL}"
}
}
}
}After saving, restart the OpenClaw gateway and verify with openclaw mcp list. You should see each server listed with its status and tool count.
The 7 MCP Servers Every OpenClaw Agent Should Run
You do not need all 10,000+ community servers. According to the Prem.ai MCP survey from March 2026, the Filesystem server is the most widely installed because it ships in most starter kits. Start with these seven and add more only when you have a specific use case.
1. Filesystem
Read, write, and search local files. Zero config beyond specifying the allowed directory. Every OpenClaw agent needs this. Package: @modelcontextprotocol/server-filesystem
2. GitHub
Search code, read pull requests, manage issues, and commit changes. The official GitHub MCP server from GitHub themselves provides 30+ tools. Requires a personal access token. Package: @modelcontextprotocol/server-github
3. Brave Search
Free web search for your agent. 2,000 queries/month on the free tier. No credit card required. This is the easiest way to give your agent web access. Package: @modelcontextprotocol/server-brave-search
4. PostgreSQL
Query databases, inspect schemas, and run read-only SQL directly. Essential if your agent manages any data-backed application. Set DATABASE_URL as an environment variable -- never put connection strings in config files. Package: @modelcontextprotocol/server-postgres
5. Slack
Slack's official MCP server provides 47 tools for workspace interaction, according to the Slack developer documentation. Search messages, post to channels, and manage workflows. Requires a Slack app with bot token. Package: @modelcontextprotocol/server-slack
6. Playwright (Browser)
Microsoft's official Playwright MCP server brings browser automation to your agent. Uses accessibility snapshots instead of screenshots for efficient interaction. Navigate pages, fill forms, click buttons -- all through MCP. Package: @playwright/mcp
7. Sequential Thinking
A meta-tool that helps the agent break down complex tasks into structured reasoning chains before executing. Not a traditional integration -- it improves the agent's decision-making on multi-step problems. Package: @modelcontextprotocol/server-sequential-thinking
stdio vs HTTP: Choosing the Right Transport
OpenClaw supports two MCP transport methods. Picking the wrong one causes connection failures and confusing error messages. Here is when to use each.
| Feature | stdio | HTTP/SSE |
|---|---|---|
| How it works | Local child process, stdin/stdout | Web service with Server-Sent Events |
| Setup effort | One CLI command | URL + optional auth headers |
| Best for | Solo use, local tools | Teams, remote/cloud services |
| Resource cost | Uses local CPU/RAM per server | Network connection only |
| Latency | Near-zero (local process) | Network-dependent (10-200ms typical) |
Rule of thumb: use stdio for everything unless you need to share the server across machines or team members. According to the MCP documentation, stdio is the most common transport and the default for all official first-party servers.
The complete playbook
MCP servers are one piece of the puzzle. The KaiShips Guide covers the full stack -- memory, skills, model routing, cron automation, and the workspace architecture behind a production agent.
This tutorial gets MCP servers running. The guide shows you how every layer fits together so your agent actually ships work.
Get the KaiShips Guide to OpenClaw -- $29Build a Custom MCP Server in 15 Minutes
When no community server covers your use case, build your own. The MCP TypeScript SDK (@modelcontextprotocol/sdk) makes this straightforward. Here is a complete example -- a server that checks Stripe account balance, built in 40 lines.
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import Stripe from "stripe";
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
const server = new McpServer({
name: "stripe-balance",
version: "1.0.0",
});
server.tool(
"get_balance",
"Get current Stripe account balance",
{},
async () => {
const balance = await stripe.balance.retrieve();
const available = balance.available
.map((b) => `${(b.amount / 100).toFixed(2)} ${b.currency.toUpperCase()}`)
.join(", ");
return {
content: [{ type: "text", text: `Available balance: ${available}` }],
};
}
);
const transport = new StdioServerTransport();
await server.connect(transport);Register It in OpenClaw
Save the file as stripe-balance-server.ts, then add it to your config:
{
"mcpServers": {
"stripe-balance": {
"command": "npx",
"args": ["tsx", "./mcp-servers/stripe-balance-server.ts"],
"env": {
"STRIPE_SECRET_KEY": "${STRIPE_SECRET_KEY}"
}
}
}
}Restart the gateway. Now your agent can check Stripe balance by calling the get_balance tool. The same pattern works for any API -- wrap the call in a tool definition, expose it over stdio, and OpenClaw handles the rest.
Managing Multiple Servers with Tool Search
Every MCP server adds its tool definitions to the agent's context window. With 10 servers exposing 5-15 tools each, that is 50-150 tool definitions consuming 5,000-15,000 tokens per API call. At Claude Sonnet pricing ($3 per million input tokens), that adds $0.015-$0.045 per message just for tool schemas.
Tool Search solves this. When set to auto mode, OpenClaw dynamically loads only the tool definitions relevant to the current task. According to the OpenClaw documentation, this reduces tool definition overhead by 60-80% on multi-server setups.
// In openclaw.json
{
"toolSearch": "auto"
}- ●Under 5 servers. Leave Tool Search off. The overhead is negligible and every tool stays instantly available.
- ●5-10 servers. Set Tool Search to auto. The agent loads tool schemas on demand with minimal latency impact.
- ●10+ servers. Tool Search is mandatory. Without it, you are paying $0.05+ per message just for tool definitions that rarely get used.
Security Hardening for MCP Servers
MCP servers can read files, query databases, and call external APIs. A misconfigured server is a security hole. According to the OpenClaw security documentation, treat every third-party MCP server as untrusted code until you have reviewed its source.
Never inline secrets
Pass API keys and tokens via environment variables using the ${VAR_NAME} syntax in your config. OpenClaw resolves these at runtime from your shell environment. Never put raw secrets in openclaw.json -- it often ends up in git.
Use tool allowlists
Restrict which tools a server can expose to the agent. If a GitHub server offers 30 tools but you only need issue search, allowlist just that tool. Fewer exposed tools means a smaller attack surface and lower token overhead.
Scope filesystem access
The Filesystem MCP server takes an allowed directory as an argument. Set it to your project directory, not your home folder. Never point it at / or ~. The tighter the scope, the less damage a misbehaving agent can do.
Audit before enabling
Read the source of any third-party MCP server before adding it to your config. Check what network calls it makes, what file access it requires, and whether it logs anything sensitive. Prefer servers from verified publishers (GitHub, Microsoft, Anthropic) when possible.
Troubleshooting Common MCP Issues
MCP server errors usually fall into three categories: connection failures, auth problems, and tool discovery issues. Here are the fixes for the most common problems.
"Server not found" after adding config
You need to restart the OpenClaw gateway after changing openclaw.json. Run openclaw restart then openclaw mcp list to verify. If the server still does not appear, check for JSON syntax errors in your config file.
"ENOENT" or "command not found"
The command specified in your config does not exist on the system PATH. For npx-based servers, make sure Node.js 18+ is installed. For Python servers, verify the Python path. Run the command manually in your terminal first to confirm it works.
Tools not showing up for the agent
If Tool Search is enabled, the agent may not load a server's tools until they are relevant to the current task. Test by explicitly asking the agent to use a specific tool. If it still fails, check the server logs with openclaw mcp logs <server-name>.
Environment variables not resolving
OpenClaw resolves ${VAR_NAME} from your shell environment at gateway start time. If a variable is empty, the server will fail silently. Export the variable in your shell profile (.zshrc or .bashrc) and restart your terminal before restarting the gateway.
Our Production MCP Config
We run KaiShips with 6 MCP servers in production. This is the actual config behind our 24/7 OpenClaw agent that writes blog posts, manages Discord, scouts job listings, and deploys to Vercel.
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem",
"/Users/kai/projects"]
},
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" }
},
"brave-search": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-brave-search"],
"env": { "BRAVE_API_KEY": "${BRAVE_API_KEY}" }
},
"postgres": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres"],
"env": { "DATABASE_URL": "${SUPABASE_DB_URL}" }
},
"playwright": {
"command": "npx",
"args": ["-y", "@playwright/mcp"]
},
"discord": {
"command": "npx",
"args": ["-y", "discord-mcp-server"],
"env": { "DISCORD_BOT_TOKEN": "${DISCORD_BOT_TOKEN}" }
}
},
"toolSearch": "auto"
}Total overhead with Tool Search on auto: roughly 1,500 tokens per API call (only active tools loaded). Without Tool Search, the same setup would add 8,000+ tokens per call. That is the difference between $0.005 and $0.024 per message at Sonnet pricing -- or $19 saved per 1,000 messages.
For more on keeping costs down with this setup, read our OpenClaw cost optimization guide.
Frequently Asked Questions
What is an MCP server in OpenClaw?
An MCP server is a lightweight process that exposes tools, resources, or prompts to your OpenClaw agent through the Model Context Protocol. OpenClaw spawns each server as a child process (stdio) or connects to it over HTTP, then routes tool calls through the protocol. The agent sees MCP tools the same way it sees built-in tools -- no special handling required.
How many MCP servers can OpenClaw run at once?
There is no hard limit. Production setups commonly run 5-12 MCP servers simultaneously. Each stdio server is a separate child process, so the practical limit is your machine's memory and CPU. On a Mac with 16GB RAM, 10-15 servers run comfortably. HTTP servers have no local resource cost beyond the network connection.
Do MCP servers increase OpenClaw API costs?
Yes, but modestly. Each MCP server adds its tool definitions to the agent's context window -- typically 200-500 tokens per server. With 10 servers, that is 2,000-5,000 extra tokens per API call. At Claude Sonnet pricing ($3/MTok input), that costs roughly $0.006-$0.015 per message. Use Tool Search (auto mode) to load tool definitions on demand and cut this overhead by 60-80%.
What is the difference between stdio and HTTP MCP transport?
Stdio servers run as local child processes communicating over stdin/stdout. They are the simplest to set up and most common for solo use. HTTP servers run as web services (often with Server-Sent Events) and are better for shared team setups, remote servers, or cloud-hosted tools. Use stdio for local tools and HTTP for shared or remote services.
Can I build my own MCP server for OpenClaw?
Yes. The MCP TypeScript SDK (@modelcontextprotocol/sdk) and Python SDK (mcp) both support building custom servers in under 50 lines of code. Define your tools with input schemas, register handlers, and connect via stdio transport. OpenClaw picks up the new server immediately after you add it to your config and restart.
Bottom Line
MCP turns your OpenClaw agent from a smart text generator into a tool-using system that can actually interact with the world. Start with Filesystem, GitHub, and Brave Search -- those three cover 80% of use cases. Add Postgres, Slack, or Playwright when you need them. Build custom servers for anything else.
The setup takes 10 minutes. The security hardening takes another 10. Enable Tool Search if you run more than 5 servers, and you will keep your token overhead under control. The MCP ecosystem is growing fast -- 97 million SDK downloads and 10,000+ community servers mean there is probably already a server for whatever tool you need to connect.
The complete playbook
MCP servers are one piece of the puzzle. The KaiShips Guide covers the full stack -- memory, skills, model routing, cron automation, and the workspace architecture behind a production agent.
This tutorial gets MCP servers running. The guide shows you how every layer fits together so your agent actually ships work.
Get the KaiShips Guide to OpenClaw -- $29