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, session visibility, 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.

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

Store the credentials Horizon uses for the remote endpoint so clients do not need direct access to that server.

Make remote traffic visible

Use Horizon request logs, sessions, 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.
SituationWhy external helps
The MCP server is already deployed and operated by another teamHorizon can protect and expose the server without changing its ownership model.
The server must stay in a specific network or runtime environmentHorizon forwards accepted requests while you keep the remote deployment where it is.
You want to standardize client access before migrating runtimeClients can move to a Horizon endpoint first; runtime migration can be a separate decision.
A sensitive remote server should not be connected to every client directlyClients authenticate to Horizon, and Horizon uses the configured remote credentials when it forwards requests.
A remote server should become a backend for a remix serverRegister it once, then include selected capabilities in a curated remix endpoint.
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.
ConcernContract
Client endpointClients use the Horizon-served MCP URL, not the remote server URL.
CapabilitiesHorizon discovers tools, resources, and prompts from the remote server.
AccessHorizon checks server and capability access before forwarding client traffic.
Remote authenticationHorizon uses the configured remote credentials when it calls the remote endpoint.
Runtime behaviorThe remote server still executes the request and owns its application behavior.
ObservabilityHorizon records gateway-level requests and sessions; remote runtime logs remain outside Horizon.
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.
ConcernHorizon managesYou manage
Client accessHorizon endpoint, authentication, authorization, capability policies, and client-facing request logs.Which users and service accounts should receive access.
Remote runtimeForwarding accepted requests to the configured endpoint.Deployment, uptime, scaling, dependencies, and application logs for the remote server.
Remote credentialsSecure storage and use of the configured remote credential.Credential issuance, rotation timing, and remote-server policy.
Metadata snapshotDiscovery, display, and policy attachment for remote capabilities.Keeping the remote capability lists valid, stable, and descriptive.
FailuresGateway status, forwarding outcomes, request metadata, and session metadata.Remote server errors, remote availability, and incorrect application responses.
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 using the remote authentication settings stored for the external server.
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 and session.

​
Authentication model

External servers have two authentication layers. Keep these layers separate when you debug a connection: a client can be signed in to Horizon and still be missing the credential Horizon needs for the remote server.
LayerWhat the user experiencesWhat Horizon does
Client to HorizonThe MCP client signs in to Horizon or sends a Horizon API key for the Horizon endpoint.Horizon authenticates the caller and applies server access and capability policy.
Horizon to remote serverThe user authorizes the remote server with OAuth or stores a remote API token in Horizon, or an admin configures one shared token for the connector.Horizon forwards accepted MCP requests to the remote server with the stored remote credential, scoped to the user or shared across the organization.
The client’s Horizon credential is not the remote credential. With OAuth and token-based authentication, Horizon stores the remote credential separately and uses it only when forwarding accepted requests to the configured remote server.

​
OAuth user experience

OAuth-backed external servers use a popup-based handoff so the user can grant Horizon access to the remote server without giving the MCP client the remote credential.
1

Configure OAuth

Horizon reads the remote server’s OAuth metadata when it is available. If the remote server supports automatic client registration, Horizon can use that. Otherwise, enter the authorization URL, token URL, client ID, client secret, and scopes manually.
2

Start authorization

The user clicks Authorize with OAuth. Horizon opens a popup and the setup page shows a waiting state while the user finishes authorization in the popup.
3

Grant remote access

The popup sends the user to the remote server’s authorization page. The user signs in there if needed and approves the requested scopes.
4

Return to Horizon

The remote authorization flow redirects back to Horizon. Horizon stores the remote credential for that user, the popup shows Authorization Complete, and the original setup or client authorization continues.
5

Call the server

The MCP client calls the Horizon endpoint with its Horizon credential. Horizon checks access, selects the caller’s stored remote credential, and forwards the accepted request to the remote server.

​
Token user experience

Token-backed external servers do not open an OAuth popup. They come in two shapes:
  • Per-user API key: each user enters their own remote token in Horizon, and Horizon uses that token only for that user’s requests.
  • Shared API key: an admin configures one token when registering the connector, and Horizon uses it for everyone in the organization.
In both cases, Horizon stores the token and sends it to the remote server using the configured header name and token prefix. Users can add, update, or revoke their per-user token from the external server’s authorization controls. A shared key is managed in the connector’s settings. After a token is saved, Horizon does not display the token value again.

​
Auth failure behavior

EventWhat the user seesWhat to fix
The MCP client is not signed in to HorizonHorizon rejects the client request or starts the Horizon client authorization flow.Sign in to Horizon or update the Horizon API key used by the client.
The user closes or denies the OAuth popupThe setup or client authorization page keeps waiting for remote authorization.Start the OAuth flow again and approve the requested scopes.
The browser blocks the popupHorizon shows that it could not open the OAuth popup, or the page remains in a waiting state.Allow popups for Horizon and retry Authorize with OAuth.
The OAuth link expires or the callback failsThe popup shows an authorization failure instead of completing.Close the popup and restart the OAuth flow from Horizon.
The stored remote credential is missing, expired, revoked, or invalidHorizon can authenticate the client, but calls to the remote server fail authorization.Reauthorize with OAuth or update the stored token.
Horizon policy denies the callerThe capability is hidden or blocked before the remote server is called.Update Horizon server access or capability policy; remote authorization will not fix this.

​
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 OAuth or token authentication for the remote server. Keep 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. Inspector, 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.
Remote changeHorizon impactRecommended action
Add a capabilityRuntime lists may show it before the dashboard snapshot or policy setup includes it.Refresh metadata, inspect the capability, and update policy if it should be governed.
Remove a capabilityClients or remixes that depend on it may fail or stop showing it.Update clients, remixes, and policies before removing it from production use.
Rename a capabilityHorizon treats the old and new names as different capabilities.Update policies and client instructions that reference the old name.
Change input schemaExisting client calls may become invalid.Test the updated schema in Inspector before updating clients.
Change remote authenticationHorizon may fail to forward requests once the old credential stops working.Update the stored remote credential before rotating the old one out.

​
List and call failure behavior

An external server has one remote backend, so list behavior depends on that backend’s response.
EventWhat clients see through Horizon
The remote server does not support a list methodHorizon returns an empty list for that capability type.
The remote server is unavailable during a list requestHorizon can return an empty list for that capability type.
The remote server returns an authentication, authorization, or protocol errorThe list request can fail instead of being treated as an empty list.
A caller is denied by Horizon capability policyThe capability is hidden from list responses and blocked when called directly.
The remote server fails while handling a selected callHorizon returns the remote failure to the client and records gateway request metadata.

​
Before clients use the server

An external server is ready for client use when Horizon can discover it, authenticate to it, 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.
  • Inspector 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.
Refresh the external server metadata after changing the remote server. Also reconnect clients that cache capability lists.
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.

Authentication

Understand client-to-Horizon and Horizon-to-server authentication.

Remix servers

Aggregate selected capabilities from multiple MCP backends behind one server.