MCP Server Configuration

What Is MCP?

MCP (Model Context Protocol) is a standard that lets your OpenClaw instance connect to external tools and data sources. An MCP server exposes specific capabilities — like file access, database queries, or API integrations — that the LLM can use when responding to messages.

When an MCP server is connected, the LLM gains access to the tools that server provides. For example, a filesystem MCP server lets the LLM read and write files on the instance. A web search MCP server lets it look up information online.

How MCP Works on ClawHosters

Your OpenClaw instance acts as an MCP client. It connects to MCP servers that run either:

• Inside the container — Built-in servers that ship with OpenClaw
• On the same host — Servers you install via SSH
• Remotely — External servers accessed over the network

The instance discovers available MCP servers from its configuration and connects to them on startup. The LLM then sees the tools these servers expose and can use them during conversations.

Built-in MCP Servers

OpenClaw includes several MCP servers out of the box:

These servers are available on all tiers. The browser server requires the pre-installed Playwright Chromium from the base snapshot.

Configuring MCP Servers

MCP server configuration is managed through the OpenClaw gateway settings. You can configure servers in two ways:

Via the Web UI

1. Open your instance's web UI (the gateway URL)
2. Navigate to Settings
3. Find the MCP Servers section
4. Add, edit, or remove server configurations

Via openclaw.json

For advanced users who SSH into their instance, MCP servers can be configured directly in the OpenClaw configuration:

{
  "mcpServers": {
    "filesystem": {
      "command": "node",
      "args": ["/app/mcp-servers/filesystem/dist/index.js"],
      "env": {}
    },
    "custom-server": {
      "command": "npx",
      "args": ["-y", "@some-org/mcp-server"],
      "env": {
        "API_KEY": "your-key-here"
      }
    }
  }
}

Each MCP server entry needs:

Installing Custom MCP Servers

You can install additional MCP servers via SSH:

1. SSH into your instance
2. Install the MCP server package (usually via npm)
3. Add the server configuration to your OpenClaw settings
4. Restart or reload the configuration

Example — installing a custom MCP server:

# SSH into your instance
ssh -i ~/.ssh/openclaw-master root@your-instance-ip

# Install inside the container
docker exec -it openclaw-<id> npm install -g @some-org/mcp-server

# Then add the server config via the web UI or openclaw.json

Keep in mind:

• Custom MCP servers persist across container restarts (if installed in the data volume)
• A rebuild wipes custom installations — reinstall after rebuild
• MCP servers run with the same permissions as the container (root)
• Broken MCP servers can cause the instance to hang or consume excessive resources

Resource Impact

MCP servers run as child processes of the OpenClaw gateway. Each server uses some memory and CPU:

On Budget tier (1 GB Docker memory limit), running many MCP servers can exhaust available memory. Monitor your memory usage if you add custom servers.

Troubleshooting

MCP Server Not Connecting

• Check that the server command exists (is the package installed?)
• Verify the arguments are correct
• Check container logs for startup errors: docker logs openclaw-<id>

Tools Not Appearing for LLM

• The LLM only sees tools from connected MCP servers
• Verify the server is running: check the gateway status in the web UI
• Some tools require the LLM add-on to be active

Browser MCP Server Issues

• Playwright Chromium is pre-installed in the base snapshot
• If browser tools fail, the Chromium installation may be corrupt
• A rebuild restores the clean browser installation

Related Documentation

• OpenClaw Configuration Reference — Full config file reference
• Skills and Plugins — How skills extend your instance
• SSH Access — Connecting to your instance
• Resource Limits — Memory and CPU by tier