OpenClaw mcporter: Manage MCP Servers Directly from Your AI Agent

You have three MCP servers running. One needs an OAuth token refresh. Another stopped responding after a config change. The third works fine but you forgot which tools it exposes. You could SSH into your machine, check each server manually, read logs, and piece together what went wrong. Or you could ask your AI agent.

The mcporter skill gives your OpenClaw agent direct control over MCP servers. List available servers, configure new ones, handle authentication flows, call individual tools, and debug connection problems — all through conversation or CLI commands.

This tutorial walks through mcporter from installation to multi-server management. By the end, you will have a repeatable workflow for managing any number of MCP servers through your agent.

What Is mcporter?

mcporter is an OpenClaw skill built by steipete. It provides a command-line interface for interacting with MCP (Model Context Protocol) servers. MCP is the protocol that lets AI agents connect to external tools and data sources through a standardized interface.

Without mcporter, managing MCP servers means editing JSON config files, restarting processes, and checking logs manually. mcporter wraps all of that into commands you can run from your terminal or delegate to your agent.

What mcporter handles:

• Discovery — List all available MCP servers and the tools they expose
• Configuration — Add, modify, and remove server configurations
• Authentication — OAuth flows, API key management, token refresh
• Tool invocation — Call any tool on any connected server directly
• Debugging — Test connections, inspect responses, trace errors
• Multi-server management — Switch between servers, compare configurations

The skill works with both HTTP-based and stdio-based MCP servers. If a server speaks MCP, mcporter can talk to it.

What You Need

Before starting:

1. OpenClaw installed and running — If you have not set up OpenClaw yet, follow the Getting Started guide. Takes about ten minutes.

2. At least one MCP server — This can be a local server running on your machine, a remote HTTP server, or any stdio-based server. If you do not have one, we will walk through connecting to a sample server below.

3. A messaging channel (optional) — Telegram, WhatsApp, Discord, or Signal connected to your agent. You can also use the terminal.

No additional API keys are required for mcporter itself. Individual MCP servers may require their own credentials.

Step 1: Install mcporter

Install the skill from ClawHub:

clawhub install mcporter

Verify the installation:

openclaw skills list

You should see mcporter in the output. The skill is now loaded and ready to use.

Step 2: List Available MCP Servers

The first thing you will want to do is see what MCP servers are already configured or discoverable. Ask your agent:

List all available MCP servers

Or use the CLI directly:

mcporter list

This returns a table of configured servers with their status:

NAME            TYPE     STATUS      TOOLS
filesystem      stdio    connected   4
github          http     connected   12
database        http     auth-needed 0
weather-api     http     disconnected 3

Each entry shows:

• Name — The identifier you use to reference the server
• Type — Whether it connects via HTTP or stdio
• Status — Current connection state
• Tools — Number of tools the server exposes

If this is a fresh install, the list may be empty. That is expected — we will add servers in the next step.

Step 3: Configure a New MCP Server

Adding an HTTP Server

To add a remote MCP server that communicates over HTTP:

mcporter add my-server --type http --url https://mcp.example.com/v1

Or through your agent:

Add an MCP server called my-server at https://mcp.example.com/v1

mcporter stores the configuration in your OpenClaw config directory at ~/.openclaw/mcp/servers.json. The structure looks like this:

{
  "servers": {
    "my-server": {
      "type": "http",
      "url": "https://mcp.example.com/v1",
      "auth": null,
      "enabled": true
    }
  }
}

Adding a Stdio Server

For local MCP servers that communicate through standard input/output:

mcporter add local-tools --type stdio --command "node /path/to/server.js"

The config entry for stdio servers stores the command instead of a URL:

{
  "local-tools": {
    "type": "stdio",
    "command": "node /path/to/server.js",
    "args": [],
    "env": {},
    "enabled": true
  }
}

Adding Environment Variables

Some servers need environment variables passed at startup:

mcporter add my-db-server --type stdio \
  --command "npx @mcp/postgres-server" \
  --env DATABASE_URL=postgres://localhost:5432/mydb \
  --env MAX_CONNECTIONS=10

Verifying the Connection

After adding a server, test it:

mcporter test my-server

This sends a handshake request and reports back:

Testing connection to my-server...
Status: connected
Protocol version: 2024-11-05
Server name: My MCP Server
Tools available: 7

If the connection fails, mcporter shows the error details. More on debugging later.

Step 4: Authentication Flows

MCP servers often require authentication. mcporter supports three methods: OAuth 2.0, API keys, and bearer tokens.

OAuth 2.0

For servers that use OAuth:

mcporter auth my-server --method oauth

mcporter starts a local callback server and opens your browser for the authorization flow:

Starting OAuth flow for my-server...
Opening browser for authorization...
Callback server listening on http://localhost:8080/callback
Waiting for authorization...

After you authorize in the browser, mcporter stores the tokens:

Authorization successful.
Access token stored for my-server.
Refresh token stored for my-server.
Token expires in 3600 seconds.

mcporter handles token refresh automatically. When a token expires, it uses the refresh token to get a new access token before the next request. You do not need to re-authorize manually.

To check the current auth status:

mcporter auth-status my-server

Server: my-server
Auth method: oauth
Token status: valid
Expires in: 2847 seconds
Last refreshed: 2026-02-24 10:15:00

API Key Authentication

For servers that use simple API keys:

mcporter auth my-server --method api-key --key sk-your-api-key-here

Or set it through an environment variable for better security:

export MCP_MY_SERVER_API_KEY=sk-your-api-key-here
mcporter auth my-server --method api-key --env MCP_MY_SERVER_API_KEY

Bearer Token

For servers that accept static bearer tokens:

mcporter auth my-server --method bearer --token your-token-here

Removing Authentication

To clear stored credentials:

mcporter auth-clear my-server

Step 5: Discover and Call Tools

Each MCP server exposes a set of tools. mcporter lets you browse and invoke them.

Listing Tools on a Server

mcporter tools my-server

Output:

TOOL                DESCRIPTION                         PARAMETERS
search_files        Search for files by name or content  query (string), path (string)
read_file           Read contents of a file              path (string)
write_file          Write content to a file              path (string), content (string)
list_directory      List contents of a directory          path (string)

Calling a Tool Directly

Call any tool with parameters:

mcporter call my-server search_files --param query="config" --param path="/home"

Through your agent:

Use mcporter to call search_files on my-server with query "config" and path "/home"

The response comes back as structured data:

{
  "result": [
    {"path": "/home/user/.config/settings.json", "type": "file"},
    {"path": "/home/user/project/config.yaml", "type": "file"}
  ]
}

Calling Tools Across Multiple Servers

If you have similar tools on different servers, you can specify which server to use:

mcporter call github search_repositories --param query="openclaw skills"
mcporter call gitlab search_projects --param query="openclaw skills"

This is useful when you want to compare results from different sources.

Step 6: Debug Server Connections

When something breaks, mcporter provides diagnostic commands.

Connection Test with Verbose Output

mcporter test my-server --verbose

This shows the full handshake process:

Connecting to https://mcp.example.com/v1...
Sending initialize request...
  -> {"jsonrpc": "2.0", "method": "initialize", ...}
  <- {"jsonrpc": "2.0", "result": {"protocolVersion": "2024-11-05", ...}}
Sending initialized notification...
Connection established.
Server capabilities: tools, resources, prompts
Tools available: 7

Checking Server Logs

For stdio servers, mcporter can capture and display stderr output:

mcporter logs local-tools --lines 50

Health Check Across All Servers

Run a health check on every configured server:

mcporter health

NAME            STATUS      LATENCY    AUTH
filesystem      connected   2ms        none
github          connected   145ms      oauth (valid)
database        error       -          api-key (set)
weather-api     connected   89ms       bearer (valid)

1 server has errors. Run 'mcporter test database --verbose' for details.

Common Connection Issues

Multi-Server Management

As your MCP setup grows, mcporter provides tools for managing multiple servers efficiently.

Server Groups

Create groups to manage related servers together:

mcporter group create dev-stack --servers filesystem,github,database

Test all servers in a group:

mcporter health --group dev-stack

Enable and Disable Servers

Temporarily disable a server without removing its configuration:

mcporter disable weather-api

Re-enable it later:

mcporter enable weather-api

Exporting and Importing Configuration

Back up your server configurations:

mcporter export > mcp-servers-backup.json

Import on another machine:

mcporter import mcp-servers-backup.json

This is useful for replicating your MCP setup across development machines or sharing configurations with teammates.

Updating Server Configuration

Modify an existing server without removing and re-adding it:

mcporter update my-server --url https://mcp.example.com/v2

mcporter update local-tools --env MAX_CONNECTIONS=20

Practical Example: Full Workflow

Here is a complete example of setting up mcporter with two MCP servers and using them through your agent.

1. Install and Configure

# Install mcporter
clawhub install mcporter

# Add a GitHub MCP server
mcporter add github --type http --url https://api.github.com/mcp

# Authenticate with GitHub
mcporter auth github --method oauth

# Add a local filesystem server
mcporter add files --type stdio --command "npx @modelcontextprotocol/server-filesystem /home/user/projects"

# Verify both servers
mcporter health

2. Use Through Your Agent

Send messages to your agent:

Search GitHub for repositories about "mcp servers" using mcporter

List all files in my projects directory using the files MCP server

Check the health of all my MCP servers

3. Troubleshoot if Needed

The GitHub MCP server is not responding. Can you debug it with mcporter?

Your agent runs the diagnostic commands, identifies the issue, and reports back with a fix.

Configuration Reference

The full configuration file lives at ~/.openclaw/mcp/servers.json. Here is a complete example with multiple servers:

{
  "servers": {
    "github": {
      "type": "http",
      "url": "https://api.github.com/mcp",
      "auth": {
        "method": "oauth",
        "client_id": "your-client-id",
        "scopes": ["repo", "read:org"]
      },
      "enabled": true,
      "timeout": 30
    },
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem", "/home/user"],
      "env": {},
      "enabled": true
    },
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": ["@mcp/postgres-server"],
      "env": {
        "DATABASE_URL": "postgres://localhost:5432/mydb"
      },
      "enabled": true
    }
  },
  "groups": {
    "dev-stack": ["github", "filesystem", "postgres"]
  },
  "defaults": {
    "timeout": 15,
    "retries": 3
  }
}

What to Try Next

Once mcporter is running, extend your setup:

• Add more MCP servers — Browse community servers at MCP server registries and add them with mcporter add
• Explore automation skills — See the automation skills category for skills that pair well with mcporter
• Build your own MCP server — Use mcporter to test and debug servers you build yourself
• Combine with other skills — Use mcporter alongside google-workspace-mcp or neondb-skill for a full tool stack

For the full mcporter documentation, visit the mcporter skill page.

FAQ

What MCP protocol versions does mcporter support?

mcporter supports the MCP protocol version 2024-11-05 and later. It auto-negotiates the version during the handshake. Older servers that use pre-release protocol versions may not be fully compatible.

Can I use mcporter without OpenClaw?

mcporter is designed as an OpenClaw skill. It runs within the OpenClaw agent framework and is installed through ClawHub. You cannot use it as a standalone CLI tool outside of OpenClaw.

How many MCP servers can I manage simultaneously?

There is no hard limit. mcporter handles server connections on demand, not as persistent connections. In practice, users manage anywhere from 2 to 20 servers without performance issues. The health check command scales linearly with the number of configured servers.

Does mcporter work with remote MCP servers behind a firewall?

For HTTP servers, mcporter needs network access to the server URL. If the server is behind a firewall, you will need to configure port forwarding, a VPN, or an SSH tunnel. For stdio servers, the server process runs locally, so firewall rules do not apply.

How do I rotate OAuth tokens for security?

Run mcporter auth-clear my-server followed by mcporter auth my-server --method oauth to re-authorize. mcporter handles refresh tokens automatically during normal use, but a full re-authorization generates new tokens from scratch. Do this periodically for servers with sensitive access.

Summary

mcporter turns MCP server management into something you can do through conversation. Instead of editing config files and checking logs manually, you install one skill and let your agent handle the rest.

Start by adding your existing MCP servers. Then use the health check to verify everything connects. Once the basics work, explore tool invocation and multi-server workflows.

If you have not set up OpenClaw yet, start with the Getting Started guide. Once your agent is running, mcporter is a one-line install away.