Skip to main content
External servers are available on .
External servers connect MCP servers that run outside Horizon to the Horizon gateway. You keep the remote server in the runtime, network, and release process it already uses. Horizon gives that server a managed entry, a protected MCP endpoint, access policies, request logs, and a place in the same catalog as hosted Horizon servers. Use an external server when the server already exists, already has an owner, or must stay where it runs today, but clients and administrators still need the benefits of a shared Horizon access layer. The remote endpoint must accept HTTPS connections initiated by Horizon. If it uses an IP allowlist, see Networking. Horizon maintains global connectors for supported provider-hosted MCP servers. Select one to use its preconfigured remote endpoint, or create an organization connector for another endpoint.

Adopt without redeploying

Register an existing MCP endpoint instead of moving its code into a Horizon hosted server first.

Give clients one front door

Let clients call a Horizon endpoint while Horizon handles access checks and forwards accepted traffic to the remote server.

Keep remote credentials private

When the remote endpoint requires authentication, store its credentials in Horizon so clients do not need direct access to them.

Make remote traffic visible

Use Horizon request logs, clients, and users to understand how the external server is used through Horizon.

​
When to use an external server

Choose an external server when the runtime should stay outside Horizon, but MCP access should be managed through Horizon. If you want Horizon to build and run the server code, use a hosted server. If you want one endpoint made from selected capabilities across multiple servers, use a remix server.

​
User-visible contract

To clients, an external server behaves like a Horizon MCP server. The client connects to the Horizon endpoint, authenticates to Horizon when required, and discovers the capabilities that Horizon has learned from the remote server. Horizon does not change the remote server’s tool behavior. It governs the path to the server, records gateway activity, and forwards accepted MCP requests to the remote endpoint you configured.
If a request is rejected before it reaches the remote server, start with Horizon request logs. If the remote server receives the request and fails, debug the remote runtime where that server is operated.

​
Ownership boundary

External servers intentionally split platform responsibility from remote runtime responsibility. This boundary is the main reason to choose an external server: Horizon becomes the access and observability layer for MCP traffic without taking ownership of the remote server’s runtime.

​
Request flow

1

Client calls the Horizon endpoint

The MCP client uses the Horizon server URL. If the server is protected, the client authenticates to Horizon.
2

Horizon checks access

The gateway identifies the caller and applies the external server’s access settings, including capability policies when they are configured.
3

Horizon forwards to the remote server

Horizon sends the MCP request to the configured remote endpoint. It injects the configured remote credential, or sends no Authorization header when no authentication is selected.
4

The remote server handles the MCP call

The remote server executes the tool, resource, prompt, or template request and returns the MCP response.
5

Horizon returns the response

Horizon returns the remote response to the client and records gateway observability for the request.

​
Authentication model

The MCP client signs in to the Horizon endpoint first. Horizon then presents a separate OAuth token or API key to the remote MCP server, unless the remote server accepts anonymous requests. The external server’s Connection page shows the current remote credential status. For a public remote server, it shows that no authentication is required. Users can authorize OAuth, add or revoke a personal token, and repair an expired credential there. Server administrators can manage a shared key and its injection format. When the remote provider requires a pre-registered OAuth client, register Horizon’s callback URL exactly as https://horizon.prefect.io/oauth/external/callback. Providers that support Dynamic Client Registration receive the same callback URL during registration. For OAuth discovery, Dynamic Client Registration, manual client fields, API-key header formatting, and the complete setup flow, see External authentication.

​
Register an external server

1

Choose external server

In Horizon, create a server and choose the external server type.
2

Enter the remote MCP URL

Provide the HTTP endpoint Horizon should call when clients use the server. The endpoint must be reachable by Horizon and speak a supported MCP HTTP transport.
3

Configure remote authentication

Choose no authentication, OAuth, or token authentication for the remote server. Select no authentication only when the endpoint accepts anonymous requests. Keep required remote credentials in Horizon instead of embedding them in MCP client setup.
4

Inspect capabilities

Horizon connects to the server, performs MCP discovery, and stores the metadata it will show in the dashboard and use for access policy setup.
5

Grant access

Configure server access and capability policies for the users and service accounts that should use the external server.

​
How discovery works

When you register or refresh an external server, Horizon captures a snapshot of the remote server’s MCP metadata. Horizon initializes an MCP session with the remote endpoint, then asks for tools, prompts, and resources. Those list requests run independently, so one failed list method does not automatically discard metadata returned by the others. Horizon stores that snapshot with the external server metadata. The snapshot is used for the dashboard, client setup surfaces, remix composition, and capability policy setup. If initialization fails, metadata capture fails. If every list response is empty or unavailable, metadata capture fails because Horizon cannot tell whether the server has no useful capabilities or discovery did not work. If at least one list response succeeds, Horizon can store the metadata it received and leave the missing capability types empty. Runtime traffic still goes to the remote server. When a client calls tools/list, prompts/list, or resources/list through the Horizon endpoint, Horizon asks the remote server for the current list and applies access filtering before returning the response. Playground, ChatMCP, and external clients still depend on the runtime endpoint being able to reach the remote server.
If capability policy does not filter it, a newly added remote tool can appear in a runtime tools/list response before the dashboard snapshot has been refreshed. If capability policy is configured, refresh the external server metadata and update policy before expecting the new tool to appear.

​
Metadata and policy lifecycle

Treat remote metadata changes as compatibility changes. If the remote server adds, removes, renames, or changes a capability schema, refresh discovery and review policies before relying on the new shape in production clients.

​
List and call failure behavior

An external server has one remote backend, so list behavior depends on that backend’s response.

​
Before clients use the server

An external server is ready for client use when Horizon can discover it, use the expected remote authentication mode, and enforce the access boundary you expect. Check the server from Horizon before updating client configuration:
  • Discovery shows the tools, resources, and prompts clients should see.
  • Playground can call representative capabilities through the Horizon endpoint.
  • A caller without access receives a gateway denial instead of reaching the remote server.
  • Request logs show forwarded calls with the expected client and user metadata.
  • The team that owns the remote server can debug runtime errors outside Horizon.
These checks matter because there are two systems in the request path. Horizon can prove the gateway accepted, denied, or forwarded a request. The remote owner still needs enough runtime visibility to explain what happened after forwarding.

​
Troubleshooting

Start with where the request stopped. Horizon request logs show whether the gateway denied, forwarded, or received an error from the remote server. If forwarding succeeded, debug the remote runtime.
Confirm the remote URL is reachable from Horizon, uses a supported MCP HTTP transport, initializes successfully, and returns at least one non-empty capability list during discovery. If the remote endpoint requires authentication, confirm the remote credential configured in Horizon is current.
The client did not authenticate to Horizon successfully. Check the client credential and the external server’s Horizon access mode.
The caller authenticated to Horizon, but server access or capability policy does not allow the requested operation. Review Authorization.
Allow popups for Horizon, then retry Authorize with OAuth. If the popup opens but returns an error, restart the OAuth flow so Horizon can create a fresh authorization request.
The client-to-Horizon credential is valid, but the Horizon-to-remote credential is missing, expired, revoked, or invalid. Reauthorize with OAuth or update the stored token for the external server.
Check the remote credential configured in Horizon, then inspect the remote server’s runtime logs. Horizon can show that forwarding occurred, but the remote server owns the application response.
Confirm Playground is connected to the intended target, then refresh its live capability list. Refresh external server metadata separately when the dashboard or capability policy setup is stale.
Gateway forwarding succeeded. Inspect the remote server’s application logs and the systems that remote server calls while handling the request.

Gateway

Learn how Horizon routes and protects MCP traffic.

External authentication

Configure whether the remote server needs a downstream credential and how Horizon supplies it.

Remix servers

Aggregate selected capabilities from multiple MCP backends behind one server.

Networking

Configure reachability and source-address allowlisting for remote endpoints.