open-claw-team/.openclaw/workspace/skills/mcp-integration/SKILL.md

name, description

name	description
mcp-integration	Connect to Model Context Protocol (MCP) servers using exec and manual integration

When to use

Use when you need to:

• Access external data sources via MCP (filesystem, GitHub, databases)
• Use tools provided by MCP servers
• Integrate with existing MCP infrastructure
• Extend OpenClaw's capabilities beyond native tools

Note: OpenClaw does not have a built-in MCP client. This skill shows how to manually integrate MCP using available tools.

What is MCP?

Model Context Protocol (MCP) is a standard for LLM apps to connect to external data sources and tools. MCP servers expose:

• Resources: Read-only data
• Tools: Callable functions
• Prompts: Prompt templates

Manual Integration Approach

Since OpenClaw lacks native MCP, you need to:

1. Run MCP server as subprocess

Start an MCP server in the background:

# Example: filesystem MCP server
npx @modelcontextprotocol/server-filesystem /allowed/path &
MCP_PID=$!

# Or GitHub MCP
GITHUB_TOKEN=ghp_... npx @modelcontextprotocol/server-github &

2. Communicate via stdio

The MCP protocol uses JSON-RPC over stdio. You need to:

• Write JSON-RPC requests to server's stdin
• Read responses from server's stdout
• Handle initialization handshake

3. Wrap as custom tool

Create a shell function or script that:

• Accepts arguments (tool name, params)
• Sends JSON-RPC request to MCP server
• Returns result to OpenClaw

Example pseudo-code:

#!/bin/bash
# mcp-call.sh
TOOL="$1"
shift
PARAMS="$*"

# Send JSON-RPC request (simplified)
echo "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\",\"params\":{\"name\":\"$TOOL\",\"arguments\":$PARAMS}}" > /tmp/mcp.stdin
# Read response from /tmp/mcp.stdout

4. Use in OpenClaw

# Call MCP tool via wrapper
exec ~/.openclaw/mcp/mcp-call.sh github_create_issue --repo 'owner/repo' --title 'Bug' --body '...'

Alternative: Use OpenHarness for MCP

OpenHarness has built-in MCP support (mcp command). If MCP integration is important:

1. Run OpenHarness alongside OpenClaw
2. Use OpenHarness as MCP gateway
3. Call OpenHarness from OpenClaw via HTTP or CLI

Supported MCP Servers (Common)

• @modelcontextprotocol/server-filesystem — local file access
• @modelcontextprotocol/server-github — GitHub API
• @modelcontextprotocol/server-postgres — PostgreSQL
• @modelcontextprotocol/server-sqlite — SQLite
• @modelcontextprotocol/server-http — generic HTTP APIs

Security Considerations

⚠️ MCP servers run with your user privileges and can:

• Read/write any files in mounted paths
• Access network resources
• Use credentials (GitHub tokens, DB passwords)

Mitigations:

• Restrict filesystem paths strictly
• Use read-only tools when possible
• Limit token scopes
• Run MCP servers in sandbox if untrusted

Workflow Example: Read file via MCP

1. Start filesystem MCP:

npx @modelcontextprotocol/server-filesystem /home/user/project &

2. List resources:

# Send request manually or via script
echo '{"jsonrpc":"2.0","id":1,"method":"resources/list"}' > /proc/$PID/fd/0

3. Read a resource:

# Assuming you have a wrapper `mcp-read`
mcp-read file:///project/README.md

Implementation Difficulty

Manual MCP integration is non-trivial:

• Need to implement JSON-RPC 2.0
• Handle server initialization handshake
• Manage async notifications
• Error handling and reconnection

Recommendation: Use OpenHarness if you need MCP now, or wait for OpenClaw to add native support.

Verification Checklist

• MCP server starts successfully and stays running
• Initialization handshake completes (capabilities exchanged)
• Tool calls return expected results
• Resources are accessible and correctly formatted
• Errors are handled gracefully
• No sensitive data leaks in logs
• MCP process is properly terminated when done

Future: Native MCP Client

A proper OpenClaw MCP integration would:

• Manage server lifecycle automatically
• Provide mcp command (list-tools, call-tool, read-resource)
• Handle JSON-RPC transparently
• Cache resources
• Support multiple servers

Consider contributing this to OpenClaw if needed.