Model Context Protocol (MCP)

Model Context Protocol (MCP) is an open standard for exposing tools and resources to LLM agents over a well-defined transport. An MCP server can provide tools for querying databases, interacting with APIs, browsing the filesystem, searching code repositories — anything that can be wrapped in a function call. When you connect an MCP server to Operator OS, every tool that server advertises is automatically registered in the agent’s tool registry under the name mcp_<server>_<tool>. The agent can then call those tools exactly like any built-in tool, with no extra configuration required in the agent itself.

Tool names are normalized to [a-z0-9_-] and prefixed with the server name to avoid conflicts. If normalization is lossy (e.g. the original name contained special characters), a short hash is appended to keep names unique.

Global configuration

MCP is disabled by default. Enable it and define your servers under tools.mcp in config.json.

{
  "tools": {
    "mcp": {
      "enabled": true,
      "servers": {
        "my-server": { ... }
      }
    }
  }
}

enabled

boolean

default:"false"

Master switch for MCP. When false, no MCP servers are started regardless of individual server configs.

servers

object

default:"{}"

A map of server names to server configuration objects. Each key becomes the server identifier used in tool names (mcp_<key>_<tool>).

Per-server configuration

enabled

boolean

required

Whether this specific server should be started. Set to false to temporarily disable a server without removing its config.

type

string

Transport type: stdio, sse, or http. If omitted, the transport is auto-detected:

url is set → sse
command is set → stdio

command

string

The executable to launch for stdio transport (e.g. npx, python, ./my-server).

args

array

Command-line arguments passed to command for stdio transport.

env

object

Environment variables injected into the stdio server process. Use this to pass API keys without hard-coding them in args.

env_file

string

Path to a .env-format file whose variables are merged into the stdio server’s environment. Lines are KEY=value; lines starting with # are comments.

url

string

The endpoint URL for sse or http transport (e.g. https://mcp.example.com/mcp).

headers

object

HTTP headers sent with every request to sse or http servers. Use this to pass Authorization tokens or API keys.

Transport types

stdio
HTTP / SSE

The server runs as a child process on the same machine. Operator OS spawns the process, communicates over stdin/stdout, and manages its lifecycle.This is the most common transport for locally-installed MCP servers distributed as npm packages, Python scripts, or compiled binaries.

{
  "tools": {
    "mcp": {
      "enabled": true,
      "servers": {
        "filesystem": {
          "enabled": true,
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
        }
      }
    }
  }
}

Use env or env_file to pass secrets to the subprocess without exposing them in args:

{
  "github": {
    "enabled": true,
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": {
      "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_TOKEN"
    }
  }
}

The server runs remotely (or locally as a standalone process) and is accessed over HTTP. Operator OS acts as an HTTP client.Use "type": "sse" for servers that stream events, or "type": "http" for standard request/response. Both use the same url and headers fields. If type is omitted and url is set, sse is used automatically.

{
  "tools": {
    "mcp": {
      "enabled": true,
      "servers": {
        "context7": {
          "enabled": true,
          "type": "http",
          "url": "https://mcp.context7.com/mcp",
          "headers": {
            "CONTEXT7_API_KEY": "ctx7sk-xx"
          }
        }
      }
    }
  }
}

env and env_file are only applied to stdio servers. For HTTP/SSE servers, pass credentials via headers.

Example servers

The following examples are taken directly from config.example.json. Copy the relevant block into the tools.mcp.servers object in your config.json.

filesystem — local file access via stdio

Gives the agent read/write access to a directory tree via the official MCP filesystem server.

{
  "filesystem": {
    "enabled": true,
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
  }
}

Replace /tmp with the directory you want the agent to access. You can add multiple paths as additional arguments.

context7 — up-to-date library documentation

Fetches current documentation for libraries and frameworks from Context7’s hosted MCP endpoint.

{
  "context7": {
    "enabled": true,
    "type": "http",
    "url": "https://mcp.context7.com/mcp",
    "headers": {
      "CONTEXT7_API_KEY": "ctx7sk-xx"
    }
  }
}

Obtain an API key at context7.com.

github — repository and issue management

Exposes GitHub operations (file access, pull requests, issues, search) to the agent.

{
  "github": {
    "enabled": true,
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": {
      "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_TOKEN"
    }
  }
}

Create a personal access token with the scopes your agent needs (repo, read:org, etc.).

brave-search — Brave web search via MCP

Routes web search requests through the Brave Search API via an MCP wrapper.

{
  "brave-search": {
    "enabled": true,
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-brave-search"],
    "env": {
      "BRAVE_API_KEY": "YOUR_BRAVE_API_KEY"
    }
  }
}

This is an alternative to the built-in web_search tool — useful if you want to route all web search through a single MCP-managed process.

postgres — SQL query execution

Lets the agent run read queries against a PostgreSQL database.

{
  "postgres": {
    "enabled": true,
    "command": "npx",
    "args": [
      "-y",
      "@modelcontextprotocol/server-postgres",
      "postgresql://user:password@localhost/dbname"
    ]
  }
}

Replace the connection string with your database credentials. Grant the database user only the privileges the agent needs.

Using environment variables for secrets

Avoid putting secrets directly in args where they may appear in process listings. Use env for inline key/value pairs, or env_file to point to a file outside the config:

{
  "my-server": {
    "enabled": true,
    "command": "npx",
    "args": ["-y", "my-mcp-server"],
    "env_file": "/etc/operator/my-server.env"
  }
}

The .env file format:

# /etc/operator/my-server.env
MY_API_KEY=sk-abc123
DATABASE_URL=postgresql://user:pass@localhost/db

Variables defined in both env and env_file are merged, with env taking precedence.

How tools become available

When Operator OS starts with MCP enabled:

Each enabled server is launched (stdio) or connected to (SSE/HTTP).
The MCP client performs the protocol handshake and fetches the server’s tool list.
Each tool is wrapped in an MCPTool adapter and registered in the global ToolRegistry.
The LLM’s system prompt is updated with the new tool definitions.

If a server fails to connect, its tools are not registered and a warning is logged. The agent continues operating with the remaining tools.

Get Started

Configuration

Channels

Tools & Extensions

Deployment

Model Context Protocol (MCP)

Global configuration

Per-server configuration

Transport types

Example servers

Using environment variables for secrets

How tools become available

Build docs developers (and LLMs) love

Get Started

Configuration

Channels

Tools & Extensions

Deployment

​Global configuration

​Per-server configuration

​Transport types

​Example servers

​Using environment variables for secrets

​How tools become available

Build docs developers (and LLMs) love

Global configuration

Per-server configuration

Transport types

Example servers

Using environment variables for secrets

How tools become available