MCP Servers

The MCP servers tab of the Integrations page lets you connect external Model Context Protocol servers so the tools they expose become available to your AI Employees. You point Ema at an MCP-compatible server; Ema discovers the tools it advertises, an admin activates the server, and from then on those tools can be used like any other Tool.

The sequence is short: add the server → Ema discovers its tools → an admin activates it → add a connection (credentials) → its tools are callable.

Add an MCP server

Any builder can register an MCP server. From the MCP servers tab, select Add MCP server and fill in:

• Name: a display name for the server.
• Description: what the server's tools do.
• Endpoint URL: the MCP server's URL (for example https://api.example.com/v1/mcp).
• Authentication: how Ema authenticates to the server (see below). Defaults to None.

Select Add server. Ema probes the endpoint URL for reachability before saving: if the URL is not reachable, you'll see an error and the server won't be created. Once the probe succeeds, Ema connects to the endpoint, discovers the tools it advertises, and sets the server to Pending review. No tools are usable until an admin activates it. Adding the server registers it and discovers its tools; you supply any credentials afterward, when you add a connection.

Authentication types

Pick how Ema authenticates to the server:

For static-header MCP connectors using API key authentication, Frontier App MCP keys are accepted via the X-API-Key header.

OAuth discovery

For a server that uses OAuth 2.1 (Authorization Code), Ema probes the server's OAuth metadata when you add the server and again whenever you change its URL, and stores the result with the server: whether the server requires credentials, and whether its provider supports dynamic client registration or a client metadata document. If the probe can't complete, the stored result is unknown and the save still goes through. Servers registered before this probe was introduced have no stored result until their URL is next edited. To run a fresh discovery on demand, call POST /mcp-servers/{id}/oauth2/probe.

Discovery errors

If tool discovery fails, Ema surfaces a structured error with an actionable banner so you can diagnose and fix the problem without digging through logs. Common causes include an unreachable endpoint, an authentication failure, or a malformed MCP response. Correct the issue (for example, update the URL or credentials) and select Refresh to retry discovery.

Edit an MCP server

To change a server's endpoint URL or other settings, open the server and edit it directly. The URL field is fully editable: Ema re-probes the new URL for reachability before saving, then re-runs discovery and returns the server to Pending review so a changed endpoint never silently serves stale tools.

Add a connection

Adding the server is metadata only. It holds no credentials. To supply them, add a connection under the server and choose a connection type:

• Shared: one connection the whole workspace uses.
• User: each user connects their own account.

Then enter the credentials for the server's authentication type: an API key, a bearer token, or a username and password. For OAuth 2.1, you don't paste a token: Ema discovers the server's authorization server, registers itself as a client automatically where the server supports it, sends each user through the provider's consent screen, and refreshes access tokens on its own.

View and refresh tools

The Tools tab of a server shows the tool list for the connection you select. Because an MCP server behind per-connection credentials can return a different catalog to each connection, each connection has its own tool list that is tracked separately from the server's published snapshot.

Connection picker

When a server has one or more connections, a picker appears above the tool list. Select a connection to view the tools it can see. For global MCP servers (provided by Ema for every workspace), a Platform snapshot entry is listed first; selecting it shows the list Ema publishes to every workspace, which cannot be refreshed from here.

Each connection entry indicates whether it is a shared connection (available to the whole workspace) or your connection (your personal credentials). Connections that are not yet set up or need attention are labeled accordingly.

Source and discovery time

Below the picker, a line explains whose tool list is on screen:

• Platform snapshot: the list Ema publishes to every workspace.
• Showing tools for [name], [shared/your] connection: the tool list last discovered through that specific connection's credential.
• This is the published tool list. This connection has not been refreshed yet.: a connection exists but has never been refreshed; the published snapshot is shown as a fallback.

If the connection has been refreshed at least once, the time of last discovery is shown alongside the source line.

Refresh a connection's tools

Select Refresh to re-discover the tools available to the currently selected connection. This runs discovery through that connection's own credential and updates only that connection's tool list. It does not change the server's published snapshot or affect what other connections see.

The Refresh button is available to any builder with manage access and is enabled when a connection is selected. It is disabled when no connection is selected (including when the Platform snapshot entry is active, since Ema owns that list) or when the connection is disconnected and the server does not use OAuth (for non-OAuth servers, add credentials in the Connections section first).

For OAuth servers, selecting Refresh while disconnected opens the provider's authorization flow so you can connect and discover tools in one step.

Discovery errors per connection

A failed refresh is shown as an inline banner above the tool list. The banner includes the reason, and may offer an action:

• Retry: re-runs the refresh that failed (available when you have manage access).
• Reconnect: re-runs the OAuth authorization flow and then re-runs discovery (available for OAuth servers when manage access allows it).
• Edit server URL: opens the edit form pre-filled with the corrected URL when the backend suggests one.

A previous discovery failure is stored against the connection. If a refresh fails but the connection had a successful list before it, the banner and the previous tool list are shown at the same time. The stored failure also appears when you first open the Tools tab, not only after a failed click.

Activate and manage the server

An MCP server moves through a deliberate lifecycle:

• Pending review → an admin selects Activate to move it to Active.
• Active → its tools are callable. An admin can Disable at any time.
• Disabled / Discovery failed → an admin can Enable, which re-runs discovery and returns the server to Pending review.

From the actions menu you can View tools (the discovered tool list), Refresh tools (re-discover from the server), and Delete the server. Deletion is blocked while an active AI Employee still uses it.

View and refresh the tool list

The tool list returned by GET /mcp-servers/{id}/tools now includes a source field that tells you where the list came from, along with additional fields when the list belongs to a specific connection.

Tool list response fields

Choosing which view to read

Pass the optional ct_id query parameter to GET /mcp-servers/{id}/tools to select a view:

• Omit ct_id: returns the published snapshot on the server row (the manifest snapshot for a global connector, the registration list for a workspace-owned server). source is published.
• Pass ct_id: returns the tool list discovered through the caller's own connection under that connection template. For a shared (workspace-level) template, that is the single shared connection. For a user-level template, it is the caller's own connection. If the caller has not connected yet, or has connected but never refreshed, the response falls back to the published snapshot and source says so.

Refresh tools through a specific connection

POST /mcp-servers/{id}/connection-tools/refresh re-discovers tools using one connection's credential and stores the result against that connection only. It does not write the server's shared tool snapshot, so it is allowed on global MCP connectors (whose snapshot belongs to their published manifest). The existing POST /mcp-servers/{id}/refresh-tools continues to write the shared snapshot and still refuses a global.

Request body:

{
  "connection_template_id": "<uuid>"
}

connection_template_id is required. Without a template there is no connection to store the result against.

Response (200): Either an MCPServerToolsResponse with source: "connection" and the refreshed tool list, or a USER_CONNECTION_REQUIRED signal when the caller has no connection under the named template:

{
  "status": "error",
  "error_code": "USER_CONNECTION_REQUIRED",
  "output": {
    "connection_template_id": "<uuid>"
  }
}

Permissions: builder and above. For a user-level template, the connection is resolved by the caller's own user id, so a caller can only ever refresh their own connection. Trial workspaces cannot reach this endpoint because it makes an outbound call to the MCP server.

Use a server in another workspace or environment

There's no export/import step for MCP servers. To use the same server in another workspace or another environment, just add it again there with the same endpoint URL and authentication. Registration is lightweight, and its tools are re-discovered when you add it.

Global MCP integrations

The following MCP servers are available as global integrations in production and demo environments. Select any of them from the Integrations catalog to add them to your workspace without manually entering an endpoint URL.

Connectors in the Autopilot chat rail

When Autopilot sets up a connector during a chat, a connector card appears in the chat rail. Selecting that card navigates you directly to the relevant page:

• MCP server cards open the MCP server detail page for that specific server.
• Custom integration cards open the integration detail page for that specific integration.
• Cards with no identifiable server or integration (for example, a Knowledge Base data-source connection, or a connector the session deleted) open the integrations catalog instead.

Ema as an MCP server

Ema also exposes its own tools to MCP-aware clients through a built-in MCP gateway (the reverse direction: Ema as an MCP server). The gateway groups tools by capability area; the following groups are available.

Audit log investigation tools

The governance audit tools let an MCP client answer "who did what, when" questions against the workspace audit log. This is useful for Autopilot to investigate access or configuration changes on behalf of an admin.

What's next

• Data Connectors: sync external documents into Knowledge bases so an AI Employee can cite them.