Skip to content
Lobster

MCP Server Integration

How to Add HTTP MCP Servers to OpenClaw (via mcporter)

This guide documents the process for connecting HTTP-based MCP servers to OpenClaw using mcporter.

Note: Apple PIM is NOT an MCP server. On macOS, Apple PIM (calendars, reminders, contacts) uses native Swift CLIs invoked via exec, not MCP. Only HTTP-based services are actual MCP servers managed through mcporter. See Phase 8 of how-to-build-your-own.md for Apple PIM setup.

Overview

OpenClaw doesn’t have native HTTP MCP server configuration like Claude Code does. Instead, you use mcporter to manage HTTP MCP connections, and OpenClaw can then call these servers via mcporter.

Prerequisites

  • OpenClaw installed and running
  • Node.js/npm installed

Setup Steps

1. Install mcporter

Terminal window
npm install -g mcporter

2. Get Authentication Token (if required)

For servers that require authentication, visit the server’s token endpoint:

https://your-mcp-server.example.com/get-token

Complete the OAuth flow in your browser and copy the generated token.

3. Configure mcporter

Create or edit ~/.mcporter/mcporter.json:

{
  "mcpServers": {
    "your-server-name": {
      "baseUrl": "https://your-mcp-server.example.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_HERE"
      }
    }
  }
}

Important: The headers object format shown above is what works. Don’t use colon notation like "Authorization: Bearer token".

4. Verify Connection

Test that the server is accessible:

Terminal window
# List available tools
mcporter list your-server-name


# Call a specific tool
mcporter call your-server-name.tool_name arg1=value1

5. Use from OpenClaw

Once configured in mcporter, OpenClaw agents can call MCP tools via mcporter:

Terminal window
mcporter call your-server-name.tool_name ...

Example Configuration

{
  "mcpServers": {
    "email-server": {
      "baseUrl": "https://your-email-mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_HERE"
      }
    },
    "travel-hub": {
      "baseUrl": "https://your-travel-mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_HERE"
      }
    }
  }
}

Troubleshooting

mcporter auth Doesn’t Work

The mcporter auth and mcporter config login commands may not work correctly with OAuth flows that use Cloudflare Access or similar authentication providers. Instead:

  1. Use the server’s /get-token endpoint directly in a browser
  2. Manually configure the token in ~/.mcporter/mcporter.json

”Invalid or expired access token”

  • Verify the token was copied correctly (no extra spaces)
  • Check the headers format matches the example above
  • Tokens may expire — get a fresh one from /get-token

Server not found

  • Run mcporter list to see all configured servers
  • Check that baseUrl matches the server’s MCP endpoint exactly
  • Verify the server is accessible: curl https://your-server.example.com/mcp

Alternative: Claude Code MCP

If you’re using Claude Code (not OpenClaw), you can add HTTP MCP servers directly:

Terminal window
claude mcp add --transport http server-name https://server.example.com/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

This stores the configuration in ~/.claude.json instead of ~/.mcporter/mcporter.json.

Granting MCP Access to Restricted Agents

Restricted agents have exec in their tool policy but it’s gated by per-agent exec approvals, so they can only run allowlisted commands — not the MCP client directly. To give them access to a specific MCP server without opening up everything:

1. Create a Wrapper Script

/Users/AGENT_USER/.local/bin/travel-hub
#!/bin/bash
set -euo pipefail
TOOL="$1"; shift
[[ "$TOOL" =~ ^[a-zA-Z_][a-zA-Z0-9_]*$ ]] || { echo "Error: invalid tool name"; exit 1; }
exec mcporter call "travel-hub.${TOOL}" "$@"

2. Add to Exec Approvals Allowlist

In ~/.openclaw/exec-approvals.json, add per-agent allowlist entries:

"agents": {
  "group-agent": {
    "security": "allowlist",
    "allowlist": [
      { "pattern": "/Users/AGENT_USER/.local/bin/travel-hub" }
    ]
  }
}

Result

The agent can run travel-hub list_trips but NOT mcporter call email-server.search_emails or any other command. Defense in depth: bindings -> tool policy -> exec approvals -> wrapper script.