> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect an MCP Server

> Import tools from a remote MCP server, choose authentication, and troubleshoot discovery failures.

Connect a remote Model Context Protocol (MCP) server to import its tools as workflows in Serval. Catalyst and the help desk agent can use the imported tools, subject to your permissions and configuration.

## Supported servers

Serval supports **Streamable HTTP over HTTPS**. The server can return JSON or server-sent events in response to a request. Local processes using **stdio** and the older **HTTP+SSE transport** with separate event and message endpoints are not supported.

Tool discovery uses the MCP initialization handshake followed by `tools/list`. Serval supports paginated tool lists. Prompts, resources, sampling, and elicitation are not imported as tools.

## Authentication

Choose the method your server supports:

| Method | Setup |
| - | - |
| API key or token | Supply the headers your server requires, such as a Bearer token or X-API-Key. The credential is shared by the team. |
| OAuth client credentials | Supply the token URL, client ID, client secret, and scopes for a shared service account. |
| OAuth JWT Bearer | Configure the signing key and token exchange settings supported by your provider. |
| Per-user sign-in | Each user connects their own account through an identity provider. Choose automatic registration or a provider configured by your admin. |

### Automatic OAuth discovery

Automatic registration requires all of the following:

1. An authentication challenge from the MCP endpoint.
2. **OAuth Protected Resource Metadata (RFC 9728)**, provided through the challenge's `resource_metadata` URL or a well-known metadata URL. Its resource identifier must match the MCP endpoint.
3. **Authorization-server metadata (RFC 8414 or OpenID Connect discovery)** that identifies the authorization and token endpoints.
4. **Dynamic Client Registration (DCR, RFC 7591)** so Serval can register its OAuth client.

Serval does not support automatic registration using **Client ID Metadata Documents (CIMD)**. If the provider requires a pre-registered client, register the client with the provider and select a configured identity provider in Serval instead of automatic registration. Use the redirect URI shown by Serval when registering the client.

## Connect in Serval

1. [Create a custom application](https://docs.serval.com/sections/integrations/application.md), then open its connection settings.
2. Select **MCP Server** as the connection type.
3. Enter the **API Base URL** and **MCP endpoint path**. For `https://tools.example.com/mcp`, use `https://tools.example.com` and `/mcp`. Enter the MCP endpoint, not the provider's website or documentation URL.
4. Choose authentication and enter the required configuration. For automatic per-user OAuth, choose **Register automatically (DCR)**.
5. Save. For per-user authentication, use **Connect account** and complete the provider's sign-in flow.
6. Open **Workflows** to see the imported workflows, marked **Imported**. On **API Integration**, the **Imported workflows** section has **Workflows** and **Sync history** tabs, with import status and retry controls above them. Saving credentials or completing sign-in does not by itself mean tool discovery succeeded.

Sync keeps Serval's imported workflows up to date; it does not run the tools or verify their behavior. For shared integrations with per-user OAuth, sync may use another connected member's account.

## Troubleshooting

If saving fails, the connection form displays the error. Check the endpoint and the requirements for the selected authentication method, then save again.

If tool discovery fails, open **Imported workflows** on the **API Integration** tab. The latest completed failure remains visible above both tabs while a retry runs. Select **View error details** for its recorded diagnostic, or open **Sync history** to inspect earlier attempts. Correct the configuration, reconnect your account if needed, then select **Sync now**.

* **DNS lookup failure:** verify that the server hostname resolves from the network used by Serval.
* **Private-network address blocked:** use a self-hosted worker with direct routing for an internal server. A hostname that works from your laptop may not be reachable from Serval Cloud.
* **Wrong endpoint or unsupported transport:** confirm the URL accepts MCP Streamable HTTP requests. A normal web page, REST API, or legacy SSE endpoint cannot supply an MCP tool list.
* **Authentication or registration failure:** check credentials, scopes, metadata, and DCR support. Use a configured identity provider when automatic registration is unavailable.
* **No tools after a successful sync:** the server returned an empty tool list for the account used during discovery. Check that account's access with the provider.
* **Workflow name conflict:** review the conflicting workflow shown in the failure details, resolve the naming conflict, and retry.

Initialization and each tool-list request have a 30-second timeout. A sync can take longer because it includes multiple requests, retries, and importing the returned tools. Tool calls have a separate, longer timeout.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.