Admin Dashboard: MCP Servers

Model Context Protocol (MCP) is an open standard for connecting AI agents to external tools and data sources. The MCP Servers page lets you add, configure, and monitor MCP server connections.

Transport types

Type	Description
`stdio`	The engine spawns a local process and communicates over stdin/stdout. Best for npm packages and local scripts. Blocked in Cloud deployments (restricted by `MCPTransportPolicy`).
`sse`	The engine connects to a remote HTTP server via Server-Sent Events.
`http`	Streamable HTTP transport (current MCP standard). The engine sends HTTP requests to the server’s MCP endpoint. Best for modern hosted MCP servers.
`streamable-http`	Alias for `http`. Accepted for compatibility.

Adding from catalog

The catalog contains pre-configured, well-known MCP servers. Adding one is a one-click operation:

Click “Add from Catalog” on the MCP Servers page.
Browse or search for the server you need (GitHub, filesystem, PostgreSQL, etc.).
Click “Add” — the name, command, and args are pre-filled.
Fill in required environment variables (e.g., GITHUB_TOKEN) and save.
The engine spawns the process and discovers available tools automatically.

Adding a custom server

For servers not in the catalog, click “Add Custom” and fill in the form:

Name — unique identifier for referencing from agent configs.
Type — stdio, sse, http, or streamable-http.
Command / URL — for stdio: the command to run. For http/sse: the server URL.
Args — command-line arguments (stdio only).
Environment variables — key-value pairs passed to the process (stdio only).
Forward headers — list of HTTP header names to forward from the incoming chat request to the MCP server (SSE/HTTP only). Useful for multi-tenant MCP backends that need tenant context (e.g., X-Org-Id, X-User-Id).

# Stdio: Engine spawns the process (self-hosted only)
mcp_servers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_TOKEN: ${GITHUB_TOKEN}

  # Python MCP server
  custom-tools:
    command: python
    args: ["-m", "my_mcp_server"]
    env:
      DATABASE_URL: ${DATABASE_URL}

# HTTP: Streamable HTTP transport (current MCP standard)
  tavily:
    type: http
    url: "https://mcp.tavily.com/mcp"
    env:
      TAVILY_API_KEY: ${TAVILY_API_KEY}

# SSE: Engine connects to a running server via Server-Sent Events
  analytics:
    type: sse
    url: "http://analytics-service:3000/mcp"

Final-answer tools (return-directly)

Some tools exist to deliver the final answer rather than feed the agent more context — for example a tool that renders product cards, a chart, or a formatted recommendation. By default the ReAct loop runs one more model step after any tool, so a “final answer” tool forces an extra assistant turn that adds nothing (and on reasoning models often produces stray self-narration).

An MCP tool can declare itself terminal so the turn ends the moment it runs: its result becomes the final answer, with no follow-up model call and no trailing assistant message. The tool owner sets a vendor key in the tool’s _meta in the tools/list response:

{
  "name": "recommend_products",
  "description": "Render the final product recommendation to the user.",
  "inputSchema": { "type": "object", "properties": { "...": {} } },
  "_meta": { "syntheticbrew.ai/return-directly": true }
}

The key is namespaced per the MCP _meta specification, so it never collides with the protocol’s reserved names.
Only a literal boolean true enables it; any other value (or a missing _meta) leaves the tool’s behaviour unchanged.
No engine or agent configuration is required — the tool self-declares. Operators can still mark built-in tools terminal via the global agent.tool_return_directly list; the two sets are combined.

Monitoring and troubleshooting

Each MCP server shows a status indicator and the count of discovered tools:

Connected (green) — the server is running and tools are discovered.
Disconnected (red) — the server process crashed or the HTTP endpoint is unreachable.
Tools count — number of tools the server exposes. Click to see the full list with descriptions.