Overview

MCP (Model Context Protocol) connects external tools and data sources to PlugClaw. Once configured, an agent can use capabilities provided by an MCP Server during a conversation, such as reading a code repository, accessing selected files, querying a database, or connecting to an internal business system.

The MCP Server is the component that provides the tools. PlugClaw connects to that server and makes its available tools accessible to agents. Different MCP Servers may access different data and require different permissions, authentication methods, and runtime environments. Do not apply the same configuration based only on a service name. Check the official documentation for the specific MCP Server first and confirm its startup method, connection address, credentials, and runtime requirements.

MCP is intended for integrating an existing service or specialized tool. Completing the configuration does not automatically change every agent behavior. After the configuration is active, request a task that specifically requires the tool to confirm that the agent actually uses it.

An MCP Server may have access to files, code, databases, or internal systems. Connect only trusted servers and grant the minimum permissions required for the intended task. Do not expose tokens, API keys, passwords, or internal addresses in public documents, conversations, or troubleshooting screenshots.

Before You Begin

Prepare the following information from the MCP Server's official documentation:

Server name          A name used to identify the service in PlugClaw config and commands
Connection type      Remote MCP or local MCP
Connection/startup   A remote URL, or a local command and args
Authentication       OAuth, token, API key, request headers, or other credentials
Runtime requirements Network access, Node.js, npx, an executable, or other dependencies

A remote MCP connects to an MCP Server that is already running. Its core setting is url. The URL must be reachable from the PlugClaw runtime. If the server runs on another device, do not use a localhost address that is valid only on the server's own device.

A local MCP is an MCP Server process started by PlugClaw. Its core setting is command. The command and all required programs must exist in the PlugClaw runtime environment, not only on another computer.

MCP configuration is stored in openclaw.json. Back up the existing file before making changes. Every JSON block below is an example to merge into the current configuration; do not replace the entire file. Preserve existing settings and check that brackets, commas, and quotation marks remain valid after the merge.

Add an MCP Server

Each MCP Server is defined under mcp.servers. The basic structure is:

{
  "mcp": {
    "servers": {
      "<server-name>": {
        "enabled": true
      }
    }
  }
}

<server-name> is the name PlugClaw uses for this service. The same name is used later in status checks and OAuth login commands. Choose a clear, unique English name such as github, filesystem, or database.

Configure a Remote MCP

A remote MCP requires an MCP Server address that PlugClaw can reach. The following example is for a server that supports Streamable HTTP:

{
  "mcp": {
    "servers": {
      "<server-name>": {
        "url": "<mcp-server-url>",
        "transport": "streamable-http",
        "enabled": true
      }
    }
  }
}

transport specifies how PlugClaw connects to the server. The streamable-http value applies only when the MCP Server explicitly supports that transport. If the server documentation specifies another transport, use the value required by that service instead of assuming that all remote servers use Streamable HTTP.

For a server that requires OAuth, add auth to that server definition:

{
  "mcp": {
    "servers": {
      "github": {
        "url": "https://example.com/mcp",
        "transport": "streamable-http",
        "auth": "oauth",
        "enabled": true
      }
    }
  }
}

For a server that authenticates through a request header, add headers:

{
  "mcp": {
    "servers": {
      "example": {
        "url": "https://example.com/mcp",
        "transport": "streamable-http",
        "headers": {
          "Authorization": "Bearer ${API_TOKEN}"
        },
        "enabled": true
      }
    }
  }
}

${API_TOKEN} reads a value from an environment variable named API_TOKEN; it is not a real token to copy literally. The variable must be available to the PlugClaw process that runs the Gateway. Setting a variable only in another terminal or on another computer does not make it available automatically. Follow the MCP Server documentation for the required variable name and authentication format.

Configure a Local MCP

A local MCP is started by a command executed in the PlugClaw runtime:

{
  "mcp": {
    "servers": {
      "<server-name>": {
        "command": "<start-command>",
        "args": [
          "<arg-1>",
          "<arg-2>"
        ],
        "enabled": true
      }
    }
  }
}

command identifies the program to start, and args lists the arguments passed to that program in order. Omit args when the command requires no arguments. For example, if the official instructions use npx -y <mcp-server-package>, set command to npx and place the remaining values in args; do not put the entire command line into command.

To pass environment variables to a local MCP Server, add env:

{
  "mcp": {
    "servers": {
      "example-local": {
        "command": "npx",
        "args": [
          "-y",
          "<mcp-server-package>"
        ],
        "env": {
          "TOKEN": "${TOKEN}"
        },
        "enabled": true
      }
    }
  }
}

Both <mcp-server-package> and ${TOKEN} are placeholders that must be prepared according to the actual service instructions. Pass sensitive values through environment variables instead of writing them directly into openclaw.json.

Apply the Configuration and Complete Authentication

Save openclaw.json and restart the Gateway so PlugClaw reloads the MCP configuration. If the Gateway no longer starts, restore the previous configuration backup and inspect the JSON structure and newly added settings instead of continuing to add changes to an invalid file.

An MCP Server that uses OAuth also requires a terminal login:

openclaw mcp login <server-name>

For example, if the configured server name is github:

openclaw mcp login github

The name in the command must exactly match the name under mcp.servers. For a server that uses a token, API key, or custom header, confirm that the required environment variable is configured and available to the PlugClaw process running the Gateway.

Verify That the MCP Server Works

First inspect the saved MCP configuration from the terminal:

openclaw mcp status --verbose

status checks the saved configuration, resolved transport, and authentication state. It does not connect to the target MCP Server. To confirm that the service can establish a live connection and expose tools, run:

openclaw mcp doctor <server-name> --probe

Replace <server-name> with the actual configured name. After the probe succeeds, return to an agent conversation and request a small task that can only be completed through that MCP Server. For a repository server, read known repository information. For a filesystem server, read a test file inside the authorized directory.

The configuration is fully verified only when the live probe succeeds and the conversation result actually comes from the target MCP Server. A normal text response from the agent does not by itself prove that an MCP tool was called.

If the MCP Server does not work, check the following in order:

• Remote MCP: Confirm the URL, verify that PlugClaw can reach it, and check that transport matches the service requirements.
• Local MCP: Confirm that command exists, args are in the correct order, and all dependencies are installed in the PlugClaw runtime.
• Authentication: Confirm OAuth login, token or API-key validity, and whether the Gateway can read the required environment variables.
• Configuration file: Check the JSON syntax, server-name consistency, and whether enabled is true.
• Permissions: Confirm that the MCP Server may access the repository, directory, database, or other resource required by the task.

To disable an MCP Server temporarily, set its enabled value to false and restart the Gateway. Remove the server definition only after confirming it is no longer needed, and keep a restorable configuration backup before deleting it.