Skip to content
Lobster | OpenClaw Playbook

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.

Prefer native OpenClaw plugins over mcporter when available. Apple PIM, Fastmail, and Travel Hub all run as native OpenClaw plugins that register tools directly with the gateway — no mcporter middleman for the main agent. This guide covers mcporter for MCP servers that don’t have a native plugin, and the wrapper-script pattern for giving restricted agents narrow access to a single MCP server.

  • Apple PIM: Native plugin apple-pim-cli — see Phase 8
  • Fastmail: Native plugin fastmail-cli — see Fastmail Plugin Setup
  • Travel Hub: Native plugin travel-hub for the main agent. Restricted agents (family, group) get narrow access through a travel-hub mcporter wrapper script that’s allowlisted in ~/.openclaw/exec-approvals.json.

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. Restricted agents typically also allowlist a handful of read-only utilities (/bin/date, /bin/cat, /bin/ls, /usr/bin/{head,tail,grep,wc}) for diagnostics on top of the wrapper script itself:

"agents": {
  "group-agent": {
    "security": "allowlist",
    "allowlist": [
      { "pattern": "/Users/AGENT_USER/.local/bin/travel-hub" },
      { "pattern": "/bin/date" },
      { "pattern": "/bin/cat" },
      { "pattern": "/bin/ls" },
      { "pattern": "/usr/bin/head" },
      { "pattern": "/usr/bin/tail" },
      { "pattern": "/usr/bin/grep" },
      { "pattern": "/usr/bin/wc" }
    ]
  }
}

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.