MCP

When to use MCP

Reach for an MCP server when someone has already published one for the integration you want — filesystem, GitHub, Slack, Linear, Postgres. You drop a JSON config; omp handles the handshake, OAuth, reconnection, and tool registration. If you need bespoke logic, write a custom tool instead.

Config file

omp reads mcp.json from these locations, in priority order:

• .omp/mcp.json — project, omp-managed

• ~/.omp/agent/mcp.json — user, omp-managed

• .claude/, .cursor/, .vscode/, .gemini/, .windsurf/, opencode.json — discovered automatically

• mcp.json or .mcp.json at the repo root — standalone fallback, lowest priority

Project entries shadow user entries with the same key. Disable a server without deleting its config by adding its key to disabledServers in the user file (~/.omp/agent/mcp.json).

stdio transport

Spawn a local process. omp pipes JSON-RPC over its stdin/stdout.

{
  "$schema": "https://raw.githubusercontent.com/can1357/oh-my-pi/main/packages/coding-agent/src/config/mcp-schema.json",
  "mcpServers": {
    "fs": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "${HOME}/projects"],
      "env": {
        "LOG_LEVEL": "info"
      },
      "cwd": "${HOME}"
    }
  }
}

type defaults to "stdio" when command is set. ${VAR} and ${VAR:-default} are expanded at load time across command, args, env, cwd, url, headers, auth, and oauth.

Streamable HTTP transport

Connect to a remote endpoint. Send a bearer token through headers or wire OAuth through oauth.

{
  "$schema": "https://raw.githubusercontent.com/can1357/oh-my-pi/main/packages/coding-agent/src/config/mcp-schema.json",
  "mcpServers": {
    "linear": {
      "type": "http",
      "url": "https://mcp.linear.app/sse",
      "headers": {
        "Authorization": "Bearer ${LINEAR_TOKEN}"
      }
    },
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "oauth": {
        "clientId": "${GH_CLIENT_ID}",
        "clientSecret": "${GH_CLIENT_SECRET}"
      }
    }
  }
}

For OAuth servers, complete the flow with /mcp reauth <name>. Credentials land in agent.db (readable only by your user); nothing is written back to the JSON.

Discovery and scoping

Tools surface as mcp__<server>_<tool>. The prefix keeps two servers with the same upstream tool name distinct. Connect, list, and tool-load happen in parallel with a 250 ms fast-start gate — cached tool definitions appear immediately as deferred handles while slow servers finish their handshake. Failures are isolated per server, transports auto-reconnect with backoff.

On-demand activation

For large catalogs, loading every MCP tool into the prompt wastes context. Set tools.discoveryMode: mcp-only in ~/.omp/agent/config.yml and MCP tools are gated behind a discovery step: the model sees a single search_tool_bm25 tool, searches it for the capability it needs, and only the matching tools materialise into the active tool set. The default auto mode does this automatically once the tool set grows past 40 tools.

tools:
  discoveryMode: mcp-only # or "auto" (default), "off", "all"

Slash commands

/mcp add, /mcp enable, /mcp disable, and /mcp reauth write back to the omp-managed file and add the $schema line automatically.

Related

• Custom tools — write your own tool instead of adopting an MCP server.

• Plugins — bundle an MCP config with skills, commands, and hooks.

• Settings — tools.discoveryMode and related knobs.\n