Admin Dashboard: MCP Servers

MCP Servers connect agents to external tools. SyntheticBrew owns the client connection, discovers each server’s catalog, and executes assigned tools on the server side.

Choose a transport

Transport	Use it for
`streamable-http`	Current remote MCP servers that accept HTTP requests and may stream responses.
`http`	Remote request/response servers using the supported HTTP transport.
`sse`	Servers using the earlier long-lived SSE transport.
`stdio`	A process launched alongside an Enterprise deployment. SyntheticBrew Cloud generally uses remote transports.

You can install a verified catalog entry or choose Add Custom MCP Server and provide a name, transport, command/arguments or URL, environment values, and optional catalog refresh interval (30–86400 seconds).

Add a server

For a catalog server, open MCP Catalog, review its transport and required variables, select a supported package when alternatives are offered, supply the requested secret references, and install it. Catalog entries are templates: verify the resulting URL, command, authentication, and tools before assigning them to an agent.

For a custom server:

Choose Add Custom MCP Server and enter a stable lowercase name.
Select the transport and supply its URL or local command and arguments.
Configure authentication and only the required environment values.
Set a refresh interval when the upstream tool catalog can change.
Save and inspect Runtime Status before assigning the server.

The details panel shows configuration, current status, circuit state, tool count, connection time, status message, environment-variable names, and agents using the server. Secret values are not displayed.

Configure authentication

None for an unprotected server.
Forward Headers to pass only named request headers such as Authorization or X-Workspace-ID. Forward Authorization only when the receiving service accepts the same JWT used to call SyntheticBrew; otherwise use a separate approved header for its credential.
API Key or Service Account using the named environment-backed credential configured by your Enterprise administrator.
OAuth 2.0 when the integration supports the Admin-managed OAuth configuration.

Forwarding a user’s identity does not grant that user access automatically. The MCP server must still enforce its own user and workspace access rules.

Verify and assign tools

Save the server and open its detail panel.
Confirm Runtime Status, discovered tool count, and circuit state.
Choose Refresh tools to run tools/list again without reconnecting.
Open an agent and attach only the server/tools required for that role.
Run a representative request and inspect Tool Call Log.

The expected result is a connected server with an up-to-date catalog and narrowly scoped agent access. Changes made on this page take effect automatically; a manual Config reload is not normally required.

Some MCP tools declare return_directly. When such a tool succeeds, its result becomes the response without another model synthesis step. Use this only when the tool already returns safe, user-ready content; otherwise let the agent interpret and explain the result.

Catalog and transport failures

SSE event lines used by the sse and streaming HTTP transports support up to 1 MiB, allowing substantially larger catalogs and results than the old scanner limit. A larger single event fails with an explicit size error; reduce or split the server response so each event stays within the bound.

If an SSE stream dies, the in-flight request fails immediately with a safe error and the transport reconnects. Check Resilience for an open breaker and verify credentials and forwarded headers before resetting anything. Enterprise administrators can use service logs for the underlying network detail; Cloud customers can contact support when the server configuration is correct but the failure persists.

If Refresh tools fails, do not remove and recreate the server immediately. Confirm that the URL or command is reachable, authentication is current, and the server returns a valid tools/list response. Recreating a server can disturb agent assignments without fixing the upstream cause.