Skip to content

MCP

MindRoom is a Model Context Protocol (MCP) client: it connects to the MCP servers you configure, discovers their tools, and lets agents call them. MindRoom uses MCP tools only; it does not use MCP resources or prompts. To go the other way and expose your agents' tools to external MCP clients, use the MCP Gateway.

Add an MCP Server

Configure servers in the top-level mcp_servers block of config.yaml. Each key is a server ID made of letters, numbers, and underscores. Each enabled server becomes one MindRoom tool named mcp_<server_id>; add that name to an agent's tools: list to give the agent the server's tools.

mcp_servers:
  chrome_devtools:
    transport: stdio
    command: npx
    args:
      - -y
      - chrome-devtools-mcp@latest
    tool_prefix: chrome

agents:
  browser:
    display_name: Browser
    role: Debug and inspect web apps in Chrome
    model: sonnet
    tools:
      - mcp_chrome_devtools

MCP tools work on every worker scope, including private agents.

Transports

transport Use for Required Optional Not allowed
stdio A local server that MindRoom starts as a subprocess command args, cwd, env url, headers, auth
sse A remote server with a Server-Sent Events endpoint url headers, auth command, args, cwd, env
streamable-http A remote server with a streamable HTTP endpoint url headers, auth command, args, cwd, env
mcp_servers:
  remote_http:
    transport: streamable-http
    url: https://mcp.example.com/mcp
    headers:
      Authorization: Bearer ${MCP_API_TOKEN}

Remote transports refuse loopback and private-network addresses; run local servers with stdio instead. A remote server on a private network, such as a cluster-internal service, needs allow_private_network: true; loopback, link-local and cloud metadata addresses stay refused. The opt-in opens every RFC 1918 and unique-local address to that server's URL and redirects, including MindRoom's own pods and Services, so set it only for a server you trust. localhost and *.local names stay refused, including Kubernetes *.svc.cluster.local; use the short Service name or <service>.<namespace>.svc.

Credentials in Server Config

env and headers values support ${ENV_VAR} placeholders, resolved from MindRoom's environment when the connection opens. Pass stdio credentials through env, never through args. config_manager and !config show mask env and headers values, except values that are a whole ${ENV_VAR} placeholder, but show args as written, and args support no placeholders.

Without OAuth, every agent and requester shares one server session and the same static headers, and MindRoom never passes the requester's identity or credentials to the server. For per-user or per-agent accounts on a remote server, use OAuth.

Tool Names

There are two names to keep apart:

  1. The tool entry in an agent's tools: list is mcp_<server_id>.
  2. The function names the model sees are <prefix>_<remote_tool_name>, where the prefix is tool_prefix or, if unset, the server ID.

With tool_prefix: chrome, a remote tool named navigate_page becomes chrome_navigate_page. A final function name must be 64 characters or fewer. A server whose tools repeat a function name, or take a name its OAuth connection functions use (<prefix>_connection_status, <prefix>_list_tools, <prefix>_call_tool), fails to list valid tools. When an MCP function has the same name as another of an agent's tools or another server's function, that agent is not offered the MCP function, and MindRoom logs a warning naming both; the server and its other functions stay available, and agents without both keep every function. Rename such a function with tool_prefix, or drop it with exclude_tools.

Choose Which Tools an Agent Sees

include_tools and exclude_tools on the server filter the catalog for every agent. To narrow it for one agent, set overrides where you assign the tool:

agents:
  browser:
    tools:
      - mcp_chrome_devtools:
          include_tools:
            - new_page
            - navigate_page
            - take_snapshot
          call_timeout_seconds: 180

Per-agent overrides accept include_tools, exclude_tools, and call_timeout_seconds (greater than 0). Filters match remote MCP tool names, not prefixed function names, and a name cannot appear in both include_tools and exclude_tools.

Dashboard Name and Icon

display_name, summary, and icon control how the server appears in the dashboard tool catalog and on Connections; they do not change tool names or permissions.

mcp_servers:
  team_wiki:
    display_name: Team Wiki
    summary: Search and edit team documentation
    icon: SiConfluence
    transport: streamable-http
    url: https://wiki.example.com/mcp

icon takes a Lucide icon name such as Book or Calendar, or a bundled React Icons name such as SiConfluence or SiGooglecalendar. Without a usable icon, Connections picks one matching the server's name, or a plug icon.

Server Options

Option Type Default Notes
enabled bool true Set to false to disable the server without removing its config
transport string required stdio, sse, or streamable-http
command string null Required for stdio
args list[string] [] stdio arguments; shown unmasked, so never put credentials here
cwd string null stdio working directory
env map[string,string] {} stdio environment variables; supports ${ENV_VAR}
url string null Required for sse and streamable-http
headers map[string,string] {} Remote request headers; supports ${ENV_VAR}
allow_private_network bool false Let a remote server's URL reach private-network addresses (RFC 1918 or IPv6 unique-local), such as a cluster-internal service; loopback, link-local and cloud metadata addresses stay refused
auth object null OAuth settings for remote servers; see OAuth Settings
tool_prefix string server ID Prefix for model-visible function names; letters, numbers, and underscores
include_tools list[string] [] Allowlist of remote tool names
exclude_tools list[string] [] Denylist of remote tool names; must not overlap include_tools
display_name string null Catalog name; falls back to auth.display_name, then a name derived from the server ID
summary string null Short capability summary for the dashboard and catalog
icon string null Dashboard and Connections icon name
description string null What the server offers, added to the OAuth bridge tool descriptions the model sees; requires auth
required bool false Keep dependent agents and teams from starting while the server is unavailable
startup_timeout_seconds float 20.0 Time allowed to connect, initialize, and list tools; must be greater than 0
call_timeout_seconds float 120.0 Default timeout per tool call; must be greater than 0
max_concurrent_calls int 1 Maximum concurrent tool calls to the server; at least 1
auto_reconnect bool true Reconnect for later calls after a dropped connection or timeout; the failed call is never replayed

OAuth-Backed Remote MCP

Use auth.type: oauth when a remote MCP server needs an OAuth bearer token, so each connection belongs to the right user or agent. OAuth requires sse or streamable-http.

mcp_servers:
  example:
    transport: streamable-http
    url: https://mcp.example.com/mcp
    tool_prefix: example
    description: Example workspace search, documents, and calendar for the signed-in user.
    auth:
      type: oauth
      display_name: Example MCP
      discovery: auto

agents:
  assistant:
    display_name: Assistant
    role: Use the user's Example workspace
    model: sonnet
    worker_scope: user_agent
    tools:
      - mcp_example

The connection follows the agent's effective scope (private.per, then worker_scope, then defaults.worker_scope), as described in Where Connections Are Stored. Changing an agent's scope changes whose connection it uses, and MindRoom never copies a credential into the new scope, so reconnect there.

Connecting and Bridge Tools

Every OAuth-backed server always exposes three functions:

  • <prefix>_connection_status
  • <prefix>_list_tools
  • <prefix>_call_tool

Before the account is connected, these are the only functions the model sees, so set description to tell the model what connecting unlocks. When no account is connected, they return a connect link (see OAuth onboarding in conversation). After connecting, <prefix>_list_tools returns the server's tools and <prefix>_call_tool calls them with that connection's token. Once MindRoom has loaded the catalog for that connection, the agent also gets typed <prefix>_<remote_tool_name> functions.

A temporary token refresh failure returns MCP server '<server_id>' OAuth token refresh failed; retry shortly and keeps the stored credentials. To reset a stuck or revoked connection, see Reset A Connection.

Endpoint Discovery

With discovery: auto, MindRoom reads the OAuth protected-resource metadata (/.well-known/oauth-protected-resource) for resource, or url when resource is unset, then fetches the advertised authorization server's metadata. If no authorization server is advertised, it looks for authorization-server metadata at the resource's origin. Setting authorization_server skips the protected-resource lookup, and explicit authorization_url, token_url, or registration_url values override the discovered endpoints. Discovery fails if the authorization server does not support the configured token_endpoint_auth_method or PKCE method.

Use discovery: manual when the server publishes no metadata or you want fixed endpoints:

mcp_servers:
  example_manual:
    transport: streamable-http
    url: https://mcp.example.com/mcp
    auth:
      type: oauth
      discovery: manual
      authorization_url: https://mcp.example.com/oauth/authorize
      token_url: https://mcp.example.com/oauth/token
      registration_url: https://mcp.example.com/oauth/register

Discovery requires HTTPS, refuses loopback and private-network hosts, and does not follow redirects. For local development, set MINDROOM_MCP_OAUTH_ALLOW_INSECURE_DISCOVERY=1 to allow non-HTTPS discovery URLs and MINDROOM_MCP_OAUTH_ALLOW_PRIVATE_DISCOVERY=1 to allow loopback or private-network discovery hosts. These variables do not relax the address rules for the MCP connection itself.

OAuth Client Registration

With dynamic_client_registration: true and no stored client, MindRoom registers a client when the first user connects and reuses it for later users. With discovery: auto, when the authorization server offers no registration endpoint but advertises client_id_metadata_document_supported, the client is public (token_endpoint_auth_method: none), and MINDROOM_PUBLIC_URL is an HTTPS URL on a public DNS hostname, MindRoom uses <MINDROOM_PUBLIC_URL>/api/oauth/<provider_id>/client-metadata.json as its client ID instead. The authorization server fetches that client ID metadata document when a user connects, so it must be able to reach that URL without signing in. See Built-In Providers for when a dynamically registered client works from a hosted address. If discovery later resolves a different token endpoint, or MINDROOM_PUBLIC_URL or MINDROOM_PORT moves the callback to another localhost port or to an HTTPS address a dynamically registered client can serve, MindRoom registers a new client and logs oauth_dynamic_client_reregistered, and users connected through the old client must reconnect. With dynamic registration disabled, or when the new server offers no registration endpoint and MindRoom cannot use a client ID metadata document, connecting fails instead. If the authorization server refuses the new callback, MindRoom keeps the old client, existing connections keep working, and status and connect name the refused callback. A MINDROOM_PUBLIC_URL such as an http:// LAN address, which a dynamically registered client cannot serve, also keeps the old client, which then works only when MindRoom is opened on localhost, and a client ID metadata document client stops working.

To use your own OAuth app, store its client config in the credential service <provider_id>_oauth_client, or list other services in client_config_services. Tokens are stored in <provider_id>_oauth; when provider_id does not start with mcp_, both service names get an mcp_ prefix. Public clients (token_endpoint_auth_method: none) need only client_id; confidential clients also need client_secret. MindRoom never re-registers an operator-configured client, so for a confidential client pin authorization_server or token_url to keep the server's metadata from redirecting its secret to another token endpoint. See Provider And Credential Service Rules for client config service rules.

OAuth Settings

auth field Type Default Notes
type string required Must be oauth
provider_id string mcp_<server_id> OAuth provider ID; letters, numbers, and underscores
display_name string null Provider name; defaults to MCP <Server Id>
resource string server url Protected resource used for discovery
discovery string auto auto or manual
authorization_server string null Authorization server issuer or base URL; skips protected-resource discovery
authorization_url string null Authorization endpoint; required for manual
token_url string null Token endpoint; required for manual
registration_url string null Dynamic client registration endpoint
dynamic_client_registration bool true Obtain a client automatically, by dynamic registration or client ID metadata document
token_endpoint_auth_method string none none, client_secret_post, or client_secret_basic
pkce_code_challenge_method string S256 S256, or null to disable PKCE
scopes list[string] [] Requested OAuth scopes
extra_auth_params map[string,string] {} Extra authorization request parameters, such as resource
extra_token_params map[string,string] {} Extra code-exchange and refresh parameters; treated as secret
client_config_services list[string] [] Credential services holding the OAuth client config, in lookup order; defaults to <provider_id>_oauth_client
shared_client_config_services list[string] [] Shared client config services checked after client_config_services

Examples

Echo Server

A minimal local server, saved as echo_mcp_server.py:

from mcp.server.mcpserver import MCPServer

server = MCPServer("Echo Server")


@server.tool()
def echo(text: str) -> str:
    return f"echo:{text}"


if __name__ == "__main__":
    server.run()
mcp_servers:
  echo:
    transport: stdio
    command: ./.venv/bin/python
    args:
      - ./echo_mcp_server.py

agents:
  code:
    display_name: Code
    role: Test MCP tools
    model: sonnet
    tools:
      - mcp_echo

The model sees the remote echo tool as echo_echo. Use a Python interpreter that has the mcp package installed. To serve it remotely instead, run server.run(transport="sse") (endpoint /sse) or server.run(transport="streamable-http") (endpoint /mcp).

Chrome DevTools

The Add an MCP Server example starts chrome-devtools-mcp, which launches its own Chrome with a dedicated profile. To attach to an already running debuggable Chrome instead, add --browser-url:

mcp_servers:
  chrome_devtools:
    transport: stdio
    command: npx
    args:
      - -y
      - chrome-devtools-mcp@latest
      - --browser-url=http://127.0.0.1:9222
    tool_prefix: chrome

If Chrome starts slowly, increase startup_timeout_seconds; if browser operations run long, increase call_timeout_seconds.

MemPalace Memory

MemPalace is a local memory store with MCP tools for search and adding memories. Running it through uvx keeps its ChromaDB version separate from MindRoom's:

mcp_servers:
  mempalace:
    transport: stdio
    command: uvx
    args:
      - --from
      - mempalace
      - python
      - -m
      - mempalace.mcp_server
      - --palace
      - /path/to/.mempalace/palace
    startup_timeout_seconds: 30
    call_timeout_seconds: 60

agents:
  assistant:
    display_name: Assistant
    role: General assistant with persistent memory
    model: sonnet
    tools:
      - mcp_mempalace

Initialize and seed the same palace before the server can return results:

uvx mempalace --palace /path/to/.mempalace/palace init /path/to/content
uvx mempalace --palace /path/to/.mempalace/palace mine /path/to/content

See the MemPalace CLI reference for these commands.

Failures and Catalog Changes

MindRoom connects to MCP servers at startup and whenever config.yaml changes, and logs a warning for each server that fails to start, initialize, or list valid tools. By default a failed server does not block anything: agents and teams that use it start without its tools. MindRoom keeps retrying a failed server without OAuth in the background and restarts the affected agents and teams once it recovers. An OAuth-backed server is retried on its next tool call. Set required: true to keep dependent agents and teams from starting until the server is available.

Errors that the MCP server reports for a tool call return to the agent as tool errors and are not retried. If the connection drops or times out during a call, the call fails even when auto_reconnect restores the connection, and the action is never replayed. Check whether a call that changes something actually completed before retrying it.

When a server reports that its tool list changed, MindRoom reloads the list, at most once a minute per server. If the tools changed, the agents and teams that use the server restart to pick them up, waiting for active responses like a config reload.