145 lines
4.1 KiB
Markdown
145 lines
4.1 KiB
Markdown
---
|
|
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.
|