Skip to main content
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:

​
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, 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.