Extending OpenClaw with MCP
OpenClaw’s skill system just leveled up. With Model Context Protocol (MCP) server support, you can connect external tools and APIs directly to your agent, giving it capabilities that weren’t possible before.
This guide walks through setting up MCP servers in OpenClaw—from basic configuration to handling common errors. By the end, you will be able to extend your agent with databases, GitHub operations, file system access, and any other service that provides an MCP server.
What is MCP?
Model Context Protocol is an open standard for connecting AI assistants to external data sources and tools. Think of it as a universal connector: instead of writing custom integrations for each service, MCP provides a standardized way to expose tools, resources, and prompts to AI systems.
MCP servers expose capabilities through a defined protocol, and MCP clients—like OpenClaw—discover and invoke those capabilities at runtime. The protocol handles authentication, request routing, response formatting, and error propagation. For tool builders and AI application developers, it eliminates the need to write custom glue code for every external service.
For OpenClaw users specifically, this means:
- Database access without writing SQL skills
- GitHub and GitLab operations without custom scripts
- Web scraping through structured APIs
- File system operations on remote machines
- Email and calendar integrations
- OpenAPI-based API access
Configuration Basics
OpenClaw stores MCP server configuration in openclaw.json. Here is a minimal configuration showing GitHub and filesystem servers:
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@github/github-mcp-server"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
}
},
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/home/user/workspace"
]
}
}
}The configuration accepts command—the executable to run such as Node, Python, or a binary—args which are arguments passed to the command, and env for environment variables with ${VAR} syntax for secrets that should not be committed to version control.
Installing Popular MCP Servers
File System Access: The filesystem server gives OpenClaw read and write access to a specified directory. This enables local file operations, code editing, document generation, and data processing. Always scope the path narrowly—grant access only to directories you would let the agent modify directly.
GitHub Integration: This requires Node.js 18 or later. Install via npm: npm install -g @github/github-mcp-server. Set GITHUB_PERSONAL_ACCESS_TOKEN in your environment. Create tokens at GitHub Settings, Developer Settings, Personal Access Tokens. The server needs repo and read:org scopes for most operations.
Database Access (PostgreSQL): Configure with the PostgreSQL MCP server package using your connection string.
Testing Your Setup
After editing openclaw.json, restart OpenClaw to pick up changes. Verify MCP tools appear in the system prompt by asking what MCP tools are available. The response should list configured servers and their exposed functions.
Common Errors and Fixes
MCP server failed to start: This usually indicates missing Node.js executable in PATH, incorrect path to the MCP server package, or missing required arguments. Fix it by testing the command manually: npx -y @github/github-mcp-server –help
ENV variable not found: OpenClaw resolves ${VAR} syntax at startup. If the variable is empty, the MCP server receives an empty string. Verify the variable exists: echo $GITHUB_TOKEN. Set it in your shell profile or environment before starting OpenClaw.
Tool execution failed: The MCP server started but the tool call failed. Check that authentication tokens have not expired, required permissions are granted, and API rate limits have not been hit.
Security Considerations
MCP servers have broad access. Follow these practices:
- Use dedicated service accounts, not personal tokens
- Scope filesystem access to specific directories, not entire home folders
- Rotate credentials regularly and use short-lived tokens when possible
- Review MCP server permissions—some request broader access than needed
- Run MCP servers in isolated environments when possible
- MCP servers do not persist across OpenClaw sessions
Advanced: Bundled MCP in Skills
Recent OpenClaw versions support MCP servers bundled in skills. These run through Pi—the embedded Pi environment—instead of requiring external configuration. Marketplace bundles like Context7 work out of the box this way. Place them in your skills directory and OpenClaw auto-discovers their MCP capabilities.
Limitations Today
- MCP tool calls do not persist across OpenClaw sessions
- Error messages from MCP servers can be opaque
- Some MCP servers require specific Node.js versions
- Windows support varies by MCP server implementation
Getting Help
The OpenClaw community tracks MCP issues and compatibility at the GitHub repository. When reporting problems, include your openclaw.json MCP section with secrets redacted, the output of openclaw doctor, and the exact command or tool call that failed.
Key Takeaways
- MCP extends OpenClaw with external capabilities without custom skills
- Configuration lives in openclaw.json with command, args, and env structure
- Test MCP commands manually before adding to configuration
- Use dedicated credentials with minimal required permissions
- Bundled MCP in skills simplifies deployment for common use cases