Contact

OpenClaw MCP Integration Guide (2026): Connect 100+ Tools to Your AI Agent

Otman HeddouchOtman Heddouch
13 min read
OpenClaw MCP Integration Guide (2026): Connect 100+ Tools to Your AI Agent

Why MCP integration matters for OpenClaw in 2026

The Model Context Protocol (MCP) has become the de facto standard for connecting AI agents to external tools and data sources. For OpenClaw users, MCP integration unlocks a critical capability: your self-hosted agent can now safely interact with hundreds of external services without hardcoding credentials or writing custom integrations.

As of February 2026, OpenClaw has native MCP server support using @modelcontextprotocol/sdk@1.25.3. This means you can connect your agent to:

  • Database systems (PostgreSQL, MySQL, MongoDB)
  • Cloud platforms (AWS, GCP, Azure)
  • Development tools (GitHub, GitLab, Jira)
  • Communication platforms (Slack, Notion, Confluence)
  • AI services (vector databases, image generation, transcription)
  • Custom internal tools via stdio or HTTP transport

This guide covers everything you need to know about OpenClaw MCP integration — from basic setup to production security patterns.

Keyword strategy

Primary keyword: OpenClaw MCP integration

Secondary keywords:

  • Model Context Protocol OpenClaw
  • OpenClaw MCP tools setup
  • MCP server configuration OpenClaw
  • OpenClaw external tools integration
  • self-hosted AI agent MCP
  • OpenClaw tool security
  • MCP stdio transport OpenClaw
  • OpenClaw production MCP deployment

Understanding MCP in the OpenClaw ecosystem

What is MCP?

The Model Context Protocol is an open standard that defines how AI applications connect to external tools and data sources. Think of it as a universal adapter — instead of writing custom code for every service you want to connect, you configure an MCP server that speaks a standard protocol.

Why MCP matters for OpenClaw

OpenClaw agents run on your infrastructure with access to your files, browser, and system commands. MCP provides a security boundary between your agent and external services:

  1. Credential isolation — MCP servers hold API keys, not your OpenClaw config
  2. Capability scoping — each MCP server exposes only specific tools
  3. Audit trail — MCP tool calls are logged separately from native OpenClaw tools
  4. Transport flexibility — connect via stdio (local process) or HTTP (remote server)

OpenClaw's MCP architecture

OpenClaw implements MCP as a first-class citizen:

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  OpenClaw Agent │────▶│  MCP Client      │────▶│  MCP Server     │
│  (your agent)   │     │  (built-in)      │     │  (external tool)│
└─────────────────┘     └──────────────────┘     └─────────────────┘
                               │
                               ▼
                        ┌──────────────────┐
                        │  Tool Discovery  │
                        │  & Invocation    │
                        └──────────────────┘

When you configure an MCP server in openclaw.json, OpenClaw:

  1. Spawns the server process (stdio) or connects to HTTP endpoint
  2. Discovers available tools via MCP protocol handshake
  3. Exposes tools to the agent as callable functions
  4. Routes tool calls through the MCP client with proper error handling

Step-by-step MCP setup

Prerequisites

Before configuring MCP servers, ensure you have:

  • OpenClaw v2026.1.29 or later (MCP support requires recent version)
  • Node.js 22+ (for npm-installed MCP servers)
  • Docker (optional, for containerized MCP servers)
  • API keys for target services (GitHub, Slack, etc.)

Step 1: Verify OpenClaw version

openclaw --version

If you're on an older version, update:

# macOS/Linux
curl -fsSL https://openclaw.ai/install.sh | bash

# Or via npm
npm install -g openclaw@latest

Step 2: Choose your MCP server transport

OpenClaw supports two MCP transport modes:

stdio transport (local process)

Best for: Local tools, database clients, file-based services

{
  "mcp": {
    "servers": {
      "filesystem": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"],
        "transport": "stdio"
      }
    }
  }
}

HTTP transport (remote server)

Best for: Cloud services, shared team tools, containerized servers

{
  "mcp": {
    "servers": {
      "github": {
        "url": "http://localhost:3000/mcp",
        "transport": "http",
        "headers": {
          "Authorization": "Bearer YOUR_TOKEN"
        }
      }
    }
  }
}

Step 3: Configure MCP servers in openclaw.json

Here's a production-ready configuration with multiple MCP servers:

{
  "mcp": {
    "enabled": true,
    "servers": {
      "filesystem": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/workspace"],
        "transport": "stdio",
        "env": {},
        "disabled": false
      },
      "github": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-github"],
        "transport": "stdio",
        "env": {
          "GITHUB_TOKEN": "ghp_your_token_here"
        },
        "disabled": false
      },
      "slack": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-slack"],
        "transport": "stdio",
        "env": {
          "SLACK_BOT_TOKEN": "xoxb-your-token"
        },
        "disabled": false
      },
      "memory": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-memory"],
        "transport": "stdio",
        "disabled": false
      }
    }
  }
}

Step 4: Validate MCP server connections

After updating your config, restart the gateway:

openclaw gateway restart

Check MCP server status:

openclaw mcp status

You should see output like:

MCP Servers:
  ✓ filesystem (stdio) — 8 tools available
  ✓ github (stdio) — 12 tools available
  ✓ slack (stdio) — 6 tools available
  ✓ memory (stdio) — 4 tools available

Step 5: Test MCP tool invocation

Send a test message to your agent:

List my recent GitHub repositories and create a summary file in my workspace

The agent should:

  1. Call GitHub MCP tools to fetch repositories
  2. Call filesystem MCP tools to write the summary
  3. Report back with results

Popular MCP servers for OpenClaw

Official MCP servers (maintained by Anthropic)

ServerPackageTransportUse Case
Filesystem@modelcontextprotocol/server-filesystemstdioRead/write files in allowed directories
GitHub@modelcontextprotocol/server-githubstdioRepository management, issues, PRs
Slack@modelcontextprotocol/server-slackstdioChannel messaging, file uploads
Memory@modelcontextprotocol/server-memorystdioPersistent knowledge storage
PostgreSQL@modelcontextprotocol/server-postgresstdioDatabase queries and operations
Git@modelcontextprotocol/server-gitstdioGit operations beyond GitHub

Community MCP servers

ServerRepositoryTransportUse Case
OpenClaw MCP Bridgefreema/openclaw-mcpHTTPConnect Claude.ai to self-hosted OpenClaw
Brave SearchVariousstdio/HTTPWeb search without browser automation
NotionCommunitystdioNotion database and page management
LinearCommunitystdioIssue tracking and sprint management
PuppeteerCommunitystdioAdvanced browser automation

Custom MCP servers

You can build custom MCP servers for internal tools:

// example-mcp-server.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new McpServer({
  name: "example-server",
  version: "1.0.0"
});

server.tool(
  "get_internal_data",
  "Fetch data from internal API",
  async ({ query }) => {
    const response = await fetch(`https://internal.api/data?q=${query}`);
    return { content: [{ type: "text", text: await response.text() }] };
  }
);

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

Security best practices for MCP integration

1. Principle of least privilege

Each MCP server should have minimal required permissions:

// ❌ Bad: Overly permissive filesystem access
{
  "args": ["@modelcontextprotocol/server-filesystem", "/"]
}

// ✅ Good: Scoped to specific workspace
{
  "args": ["@modelcontextprotocol/server-filesystem", "/home/user/workspace"]
}

2. Credential isolation

Never store API keys directly in openclaw.json if possible. Use environment variables:

# ~/.openclaw/.env
GITHUB_TOKEN=ghp_your_token
SLACK_BOT_TOKEN=xoxb-your-token

// openclaw.json
{
  "mcp": {
    "servers": {
      "github": {
        "env": {
          "GITHUB_TOKEN": "${GITHUB_TOKEN}"
        }
      }
    }
  }
}

3. Network isolation for HTTP transport

When using HTTP transport, bind MCP servers to localhost only:

{
  "mcp": {
    "servers": {
      "custom-api": {
        "url": "http://127.0.0.1:3000/mcp",
        "transport": "http"
      }
    }
  }
}

Never expose MCP servers to the public internet without authentication.

4. Audit MCP tool usage

Enable logging for MCP tool calls:

openclaw logs --follow | grep mcp

Review logs periodically for unexpected tool invocations.

5. Disable unused servers

If you're not actively using an MCP server, disable it:

{
  "mcp": {
    "servers": {
      "github": {
        "disabled": true
      }
    }
  }
}

Real-world MCP workflows

Workflow 1: Automated code review pipeline

Trigger: New PR in GitHub
  ↓
MCP GitHub: Fetch PR diff and comments
  ↓
OpenClaw Agent: Analyze code quality, security issues
  ↓
MCP GitHub: Post review comments
  ↓
MCP Slack: Notify team in #code-reviews channel

Configuration:

{
  "mcp": {
    "servers": {
      "github": { /* ... */ },
      "slack": { /* ... */ }
    }
  },
  "cron": {
    "jobs": [
      {
        "id": "pr-review-check",
        "schedule": "*/30 * * * *",
        "prompt": "Check for new PRs in otman-ai/ml-hub and review them"
      }
    ]
  }
}

Workflow 2: Knowledge base sync

Trigger: Daily at 9 AM
  ↓
MCP Notion: Fetch updated pages from knowledge base
  ↓
MCP Filesystem: Write to local docs/
  ↓
OpenClaw Agent: Generate summary of changes
  ↓
MCP Slack: Post summary to #updates channel

Workflow 3: Multi-database reporting

Trigger: Weekly on Monday
  ↓
MCP PostgreSQL: Query production database
  ↓
MCP PostgreSQL: Query analytics database
  ↓
OpenClaw Agent: Correlate data, generate insights
  ↓
MCP Filesystem: Write report to reports/weekly/
  ↓
MCP Slack: Share report link with leadership

Troubleshooting common MCP issues

Issue: MCP server fails to start

Symptoms: openclaw mcp status shows server as disconnected or error state

Diagnosis:

# Check gateway logs for MCP errors
openclaw logs --follow | grep -i mcp

# Test MCP server independently
npx -y @modelcontextprotocol/server-github

Common causes:

  1. Missing environment variables — verify env section in config
  2. Command not found — ensure npm/npx is in PATH
  3. Permission denied — check file permissions for stdio transport

Fix:

# Verify environment
echo $GITHUB_TOKEN

# Test server manually
npx -y @modelcontextprotocol/server-github

# Check OpenClaw logs
openclaw logs --tail 100

Issue: Tools not discovered

Symptoms: Server connects but agent can't see tools

Diagnosis:

openclaw mcp list-tools --server github

Common causes:

  1. Server didn't complete handshake — restart gateway
  2. Tool schema invalid — check server implementation
  3. Agent model doesn't support tool calling — verify model capabilities

Fix:

# Restart gateway
openclaw gateway restart

# Verify tool discovery
openclaw mcp status --verbose

Issue: Tool calls timeout

Symptoms: Agent hangs when invoking MCP tools

Diagnosis:

# Check for slow server responses
openclaw logs --follow | grep -A5 "mcp.*timeout"

Common causes:

  1. Network latency (HTTP transport) — add timeout config
  2. Server process blocked — check server logs
  3. Large response payload — paginate or filter

Fix:

{
  "mcp": {
    "timeout": 30000,
    "servers": {
      "github": {
        "timeout": 60000
      }
    }
  }
}

Issue: Credential errors

Symptoms: MCP server returns 401/403 errors

Diagnosis:

# Verify token is set
openclaw config get mcp.servers.github.env

Common causes:

  1. Expired API token — regenerate
  2. Wrong token format — check provider requirements
  3. Token scope insufficient — add required scopes

Fix:

  1. Regenerate API token with correct scopes
  2. Update ~/.openclaw/.env
  3. Restart gateway to reload environment

Performance optimization

1. Limit concurrent MCP connections

{
  "mcp": {
    "maxConcurrentServers": 5,
    "maxConcurrentCallsPerServer": 3
  }
}

2. Use stdio for local tools

stdio transport has lower latency than HTTP for local tools:

// ✅ Prefer for local tools
{
  "command": "npx",
  "args": ["@modelcontextprotocol/server-filesystem"],
  "transport": "stdio"
}

// ❌ Avoid for local tools
{
  "url": "http://localhost:3000/mcp",
  "transport": "http"
}

3. Cache frequently accessed data

Use the Memory MCP server for caching:

User: "What were the key points from yesterday's standup?"
  ↓
Agent checks Memory MCP server
  ↓
Returns cached summary without re-fetching from Slack

4. Batch MCP tool calls

When possible, batch multiple operations:

// ❌ Inefficient: One call per file
Read file1.txt
Read file2.txt
Read file3.txt

// ✅ Efficient: Single batch call
Read files: [file1.txt, file2.txt, file3.txt]

Advanced: Building custom MCP servers

When to build custom MCP servers

Build custom MCP servers when:

  • You have internal APIs that need AI access
  • Existing MCP servers don't cover your use case
  • You need custom authentication or authorization
  • You want to expose specific workflows as tools

Basic custom server structure

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({
  name: "custom-internal-tools",
  version: "1.0.0"
});

// Define a tool with schema validation
server.tool(
  "get_user_data",
  "Fetch user data from internal system",
  {
    userId: z.string().describe("User ID to fetch")
  },
  async ({ userId }) => {
    const response = await fetch(`https://internal.api/users/${userId}`, {
      headers: {
        "Authorization": `Bearer ${process.env.INTERNAL_API_TOKEN}`
      }
    });
    
    if (!response.ok) {
      return {
        content: [{ type: "text", text: `Error: ${response.status}` }],
        isError: true
      };
    }
    
    const data = await response.json();
    return {
      content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
    };
  }
);

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

Registering custom server in OpenClaw

{
  "mcp": {
    "servers": {
      "internal-tools": {
        "command": "node",
        "args": ["/path/to/custom-mcp-server.js"],
        "transport": "stdio",
        "env": {
          "INTERNAL_API_TOKEN": "${INTERNAL_API_TOKEN}"
        }
      }
    }
  }
}

MCP vs native OpenClaw tools

When should you use MCP servers vs native OpenClaw tools?

Use CaseMCPNative OpenClaw
External API integration✅ Preferred❌ Requires custom code
File system access (local)⚠️ Both work✅ Built-in
Browser automation❌ Use browser tool✅ Native support
Shell commands❌ Use exec tool✅ Native support
Database queries✅ Preferred❌ Requires exec + CLI
Team collaboration tools✅ Preferred❌ Requires custom skill
Custom internal APIs✅ Preferred⚠️ Possible via exec

Rule of thumb: Use native OpenClaw tools for system-level operations (files, shell, browser). Use MCP for external service integration.

Future of MCP in OpenClaw

The OpenClaw team has indicated several MCP-related features in development:

  1. MCP server marketplace — Curated list of verified MCP servers (similar to ClawHub but for MCP)
  2. OAuth flow support — Built-in OAuth for MCP servers requiring user authentication
  3. MCP tool caching — Automatic caching of idempotent MCP tool calls
  4. Cross-agent MCP sharing — Multiple agents sharing MCP server connections
  5. MCP tool composition — Chain multiple MCP tools into single operations

Conclusion

OpenClaw MCP integration transforms your self-hosted AI agent from a standalone assistant into a connected automation hub. By leveraging the Model Context Protocol, you gain:

  • Security — Credential isolation and capability scoping
  • Flexibility — Connect to hundreds of services without custom code
  • Maintainability — MCP servers are independently versioned and updated
  • Community — Growing ecosystem of pre-built MCP servers

Start with one or two MCP servers (filesystem + one external service), validate your setup, then expand based on your workflow needs. Always follow security best practices: least privilege, credential isolation, and regular audit of tool usage.

The future of AI agents is not just about smarter models — it's about better connectivity. MCP is the bridge that makes OpenClaw agents truly useful in production environments.

Related resources