MCP Integration

MCP Integration for OpenClaw

Overview

Model Context Protocol (MCP) enables OpenClaw agents to integrate with external services and APIs by providing structured tool access. Use MCP integration to expose external service capabilities as tools within OpenClaw agent sessions.

Key capabilities:

• Connect to external services (databases, APIs, file systems)
• Provide 10+ related tools from a single service
• Handle OAuth and complex authentication flows
• Configure MCP servers in openclaw.json or .mcp.json

MCP Server Configuration

Method 1: openclaw.json (Recommended)

Add MCP servers to openclaw.json under the mcpServers section:

{
  "mcpServers": {
    "database-tools": {
      "command": "node",
      "args": ["~/.openclaw/servers/db-server.js", "--config", "config.json"],
      "env": {
        "DB_URL": "${DB_URL}"
      }
    }
  }
}

Method 2: Dedicated .mcp.json

Create .mcp.json at workspace root (~/.openclaw/.mcp.json):

{
  "database-tools": {
    "command": "~/.openclaw/servers/db-server",
    "args": ["--config", "~/.openclaw/config.json"],
    "env": {
      "DB_URL": "${DB_URL}"
    }
  }
}

MCP Server Types

stdio (Local Process)

Execute local MCP servers as child processes:

{
  "filesystem": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"],
    "env": {
      "LOG_LEVEL": "debug"
    }
  }
}

Use cases: File system access, local databases, custom MCP servers, NPM-packaged servers

SSE (Server-Sent Events)

Connect to hosted MCP servers with OAuth support:

{
  "asana": {
    "type": "sse",
    "url": "https://mcp.asana.com/sse"
  }
}

Use cases: Official hosted MCP servers, cloud services, OAuth-based authentication

HTTP (REST API)

Connect to RESTful MCP servers:

{
  "api-service": {
    "type": "http",
    "url": "https://api.example.com/mcp",
    "headers": {
      "Authorization": "Bearer ${API_TOKEN}"
    }
  }
}

WebSocket (Real-time)

Connect to WebSocket MCP servers:

{
  "realtime-service": {
    "type": "ws",
    "url": "wss://mcp.example.com/ws",
    "headers": {
      "Authorization": "Bearer ${TOKEN}"
    }
  }
}

Environment Variable Expansion

All MCP configurations support environment variable substitution:

{
  "env": {
    "API_KEY": "${MY_API_KEY}",
    "DATABASE_URL": "${DB_URL}"
  }
}

Best practice: Document all required environment variables. Store sensitive values in auth-profiles.json files per agent, not in plain text.

MCP Tool Naming

When MCP servers provide tools, they follow the naming pattern:

Format: mcp__<server-name>__<tool-name>

Example:

• Server: asana
• Tool: create_task
• Full name: mcp__asana__create_task

Integration with OpenClaw Agents

Agent-Specific MCP Access

Different agents can be configured to use different MCP servers based on their role:

Multi-Agent MCP Patterns

{
  "mcpServers": {
    "github": {
      "type": "sse",
      "url": "https://mcp.github.com/sse"
    },
    "jira": {
      "type": "sse",
      "url": "https://mcp.jira.com/sse"
    }
  }
}

Authentication Patterns

OAuth (SSE/HTTP)

OAuth flows handled automatically. User authenticates on first use.

Token-Based (Headers)

{
  "type": "http",
  "url": "https://api.example.com",
  "headers": {
    "Authorization": "Bearer ${API_TOKEN}"
  }
}

Environment Variables (stdio)

{
  "command": "python",
  "args": ["-m", "my_mcp_server"],
  "env": {
    "DATABASE_URL": "${DB_URL}",
    "API_KEY": "${API_KEY}"
  }
}

Security Best Practices

• Always use HTTPS/WSS (never HTTP/WS for production)
• Use environment variables for tokens, never hardcode
• Store API keys in agent auth-profiles.json files
• Restrict MCP tool access per agent based on role (principle of least privilege)
• Document required environment variables in workspace README

Error Handling

• Connection failures: Check server URL, network, and configuration
• Tool call errors: Validate inputs, check rate limits
• Configuration errors: Validate JSON syntax, test connectivity
• Auth failures: Clear cached tokens, re-authenticate, verify env vars

Quick Reference

MCP Server Types

Configuration Checklist

• Server type specified (stdio/SSE/HTTP/ws)
• Type-specific fields complete (command or url)
• Authentication configured
• Environment variables documented
• HTTPS/WSS used (not HTTP/WS)
• ~/.openclaw/ paths used (no hardcoded absolute paths)

Additional Resources

Reference Files

• references/server-types.md — Deep dive on each server type
• references/authentication.md — Authentication patterns and OAuth
• references/tool-usage.md — Using MCP tools in commands and agents