OpenClaw MCP Server Configuration and Usage Guide

Introduction

MCP (Model Context Protocol) is an open standard that defines how AI models communicate with external tools and data sources. OpenClaw deeply integrates MCP, enabling your AI assistant to interact with the filesystem, databases, APIs, and other external resources through MCP Servers.

This tutorial takes you from concepts to mastery of MCP configuration and usage in OpenClaw.

What Is MCP

Core Concepts

The core problem MCP solves is enabling AI models to use external tools in a safe, standardized way.

User message → OpenClaw → AI model → Needs a tool → MCP Client → MCP Server → Executes operation
                                                                ↓
User receives reply ← OpenClaw ← AI model ← Gets result ← MCP Client ← MCP Server

Three Core Capabilities of MCP

MCP Server Types

MCP Servers can run in two modes:

• Stdio (Standard I/O): Runs as a child process, communicating via stdin/stdout
• SSE (Server-Sent Events): Runs as an HTTP service, communicating via HTTP

Configuring MCP Servers in OpenClaw

Basic Configuration Structure

Configure MCP in ~/.config/openclaw/openclaw.json5:

{
  mcp: {
    servers: {
      // Each MCP Server has a unique name
      "server-name": {
        // Stdio mode configuration
        command: "npx",
        args: ["-y", "@package/mcp-server"],
        env: {
          // Environment variables
          API_KEY: "your-key"
        }
      },

      // Or SSE mode configuration
      "remote-server": {
        url: "http://localhost:3001/sse",
        headers: {
          "Authorization": "Bearer your-token"
        }
      }
    }
  }
}

Multiple Servers Side by Side

You can configure multiple MCP Servers simultaneously:

{
  mcp: {
    servers: {
      "filesystem": {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-filesystem",
               "--allow-read", "--allow-write", "/home/user/documents"]
      },
      "database": {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-sqlite",
               "--db-path", "/home/user/data/app.db"]
      },
      "http-fetch": {
        command: "npx",
        args: ["-y", "@openclaw-mcp/http-fetch"]
      },
      "github": {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-github"],
        env: {
          GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxxxx"
        }
      }
    }
  }
}

Common MCP Servers Explained

1. Filesystem MCP Server

Enables the AI to read and write local files — ideal for document management and data storage scenarios.

{
  mcp: {
    servers: {
      "filesystem": {
        command: "npx",
        args: [
          "-y",
          "@modelcontextprotocol/server-filesystem",
          "--allow-read",      // Allow reading
          "--allow-write",     // Allow writing
          "/home/user/docs"    // Restrict to this directory
        ]
      }
    }
  }
}

Available tools:

Security tip: Always use the path parameter to restrict the accessible directory scope. Avoid granting access to the entire filesystem.

2. SQLite Database MCP Server

Enables the AI to query and operate on SQLite databases.

{
  mcp: {
    servers: {
      "sqlite": {
        command: "npx",
        args: [
          "-y",
          "@modelcontextprotocol/server-sqlite",
          "--db-path", "/home/user/data/myapp.db"
        ]
      }
    }
  }
}

Available tools:

Usage example: when a user says "Look up last week's sales data" in chat, the AI will automatically execute a SQL query via the MCP tool and return the results.

3. HTTP Fetch MCP Server

Enables the AI to make HTTP requests and call any REST API.

{
  mcp: {
    servers: {
      "http-fetch": {
        command: "npx",
        args: ["-y", "@openclaw-mcp/http-fetch"],
        env: {
          // Optional: configure default request headers
          DEFAULT_HEADERS: '{"User-Agent": "OpenClaw/1.0"}'
        }
      }
    }
  }
}

Available tools:

4. GitHub MCP Server

Interact with GitHub repositories — view Issues, PRs, code, and more.

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

Available tools:

5. PostgreSQL MCP Server

Connect to a PostgreSQL database:

{
  mcp: {
    servers: {
      "postgres": {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-postgres"],
        env: {
          DATABASE_URL: "postgresql://user:pass@localhost:5432/mydb"
        }
      }
    }
  }
}

How MCP Works with Skills

MCP Servers give Skills the ability to interact with the outside world. Declare the MCP tools you need in your SKILL.md:

---
name: my-skill
mcp_tools:
  - filesystem    # Use filesystem tools
  - http_fetch    # Use HTTP request tools
  - sqlite        # Use database tools
---

The AI will automatically call the corresponding MCP tools as needed during Skill execution.

Practical Workflow Example

User sends: "Export last week's order data as a CSV file"

1. The AI identifies that the task requires both sqlite and filesystem MCP Servers
2. Calls sqlite.read_query to query last week's order data
3. Formats the query results as CSV
4. Calls filesystem.write_file to save the CSV file
5. Returns the file path to the user

Building a Custom MCP Server

If existing MCP Servers don't meet your needs, you can build your own.

Minimal Example (Node.js)

// my-mcp-server.js
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server({
  name: "my-custom-server",
  version: "1.0.0"
}, {
  capabilities: {
    tools: {}
  }
});

// Register a tool
server.setRequestHandler("tools/list", async () => ({
  tools: [{
    name: "greet",
    description: "Generate a greeting message",
    inputSchema: {
      type: "object",
      properties: {
        name: { type: "string", description: "Name to greet" }
      },
      required: ["name"]
    }
  }]
}));

// Handle tool calls
server.setRequestHandler("tools/call", async (request) => {
  if (request.params.name === "greet") {
    const name = request.params.arguments.name;
    return {
      content: [{ type: "text", text: `Hello, ${name}!` }]
    };
  }
});

// Start the server
const transport = new StdioServerTransport();
await server.connect(transport);

Configure it in OpenClaw:

{
  mcp: {
    servers: {
      "my-custom": {
        command: "node",
        args: ["/path/to/my-mcp-server.js"]
      }
    }
  }
}

Debugging MCP Servers

View the MCP Tool List

# View all loaded MCP tools
openclaw doctor

The output will list all connected MCP Servers and the tools they provide.

Enable MCP Debug Logs

# View MCP communication details
openclaw logs --level debug

The logs will show MCP tool call requests and responses:

[DEBUG] MCP tool call: filesystem.read_file({path: "/home/user/notes.txt"})
[DEBUG] MCP tool result: {content: [{type: "text", text: "file contents..."}]}

Test an MCP Server Independently

You can use the MCP Inspector tool to test an MCP Server on its own:

npx @modelcontextprotocol/inspector npx -y @modelcontextprotocol/server-filesystem --allow-read /tmp

This opens a web interface that lets you directly invoke and test MCP tools.

Security Best Practices

Principle of Least Privilege

{
  mcp: {
    servers: {
      "filesystem": {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-filesystem",
               "--allow-read",           // Read-only
               "/home/user/public-docs"  // Restricted directory
        ]
        // Note: --allow-write is not included
      }
    }
  }
}

API Key Security

Don't hardcode API keys in configuration files — use environment variables:

{
  mcp: {
    servers: {
      "github": {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-github"],
        env: {
          // Reference a system environment variable
          GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_TOKEN}"
        }
      }
    }
  }
}

Then set the environment variable on your system:

export GITHUB_TOKEN="ghp_xxxxx"

Network Isolation

For remote MCP Servers (SSE mode), it's recommended to:

• Use HTTPS connections
• Configure authentication tokens
• Restrict accessible IP ranges

FAQ

MCP Server Fails to Start

# Check if npx can run properly
npx -y @modelcontextprotocol/server-filesystem --help

# Check Node.js version
node --version  # Requires 22+

Tool Call Timeouts

Some MCP tools (like HTTP requests) may time out due to network conditions. You can set timeout values in the configuration:

{
  mcp: {
    // Global timeout setting (milliseconds)
    timeout: 30000,
    servers: {
      "http-fetch": {
        command: "npx",
        args: ["-y", "@openclaw-mcp/http-fetch"],
        // Set a specific timeout for this Server
        timeout: 60000
      }
    }
  }
}

AI Doesn't Call the Expected Tool

Confirm that mcp_tools is correctly declared in the Skill and that the MCP Server name matches what's in the configuration. Check debug logs to verify that the tool was properly loaded.

Summary

MCP is the cornerstone of OpenClaw's extensibility. By configuring different MCP Servers, you can give your AI assistant access to the filesystem, database queries, API calls, GitHub operations, and virtually any external resource. Understanding how MCP works and how to configure it will help you build more powerful Skills and automation workflows.