---
name: mcp-integration
description: 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:

```bash
# 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:
```bash
#!/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
```bash
# 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:
```bash
npx @modelcontextprotocol/server-filesystem /home/user/project &
```

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

3. Read a resource:
```bash
# 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.