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

# Remix

> Publish one curated MCP endpoint from selected capabilities across multiple servers.

export const remixServersPlans = "Enterprise";

<Note>
  Remix servers are available on {remixServersPlans}.
</Note>

Remix servers let you publish a purpose-built MCP server without writing a new
backend. Select capabilities from hosted and external servers, give clients one
Horizon-served endpoint, and let Horizon route each MCP call to the backend that
owns that capability.

Use a remix server when the right client experience is not "connect to every
server we operate." It is "connect to the approved set of tools for this team,
workflow, customer, partner, or agent."

<CardGroup cols={2}>
  <Card title="One endpoint per workflow" icon="route">
    Give a client one MCP URL that contains the capabilities needed for a
    specific job.
  </Card>

  <Card title="Curated capability surface" icon="sliders">
    Expose selected tools, resources, prompts, and templates instead of every
    capability from every backend.
  </Card>

  <Card title="Least-privilege access" icon="shield">
    Apply server access and capability policies to the composed endpoint users
    call.
  </Card>

  <Card title="Stable client setup" icon="arrows-rotate">
    Keep client configuration stable while backend owners add, move, or retire
    capabilities behind the remix.
  </Card>
</CardGroup>

## When to use a remix server

Remix servers are useful when clients should see a smaller, more intentional
tool surface than the full set of servers your organization operates.

| Situation                                                               | Why remix helps                                                                         |
| ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| A team needs tools from several MCP servers                             | Publish one endpoint with only the capabilities that team needs.                        |
| A partner or customer should get a narrow interface                     | Expose a small set of approved capabilities without revealing the full backend servers. |
| An agent performs a specific workflow                                   | Give the agent a focused manifest so tool selection is clearer and safer.               |
| Read-only access should be broad, but write access should be restricted | Put read and write capabilities behind different policies on the remix.                 |
| A backend is changing, but clients need a stable endpoint               | Keep the remix URL stable while updating which backend owns selected capabilities.      |

If you need Horizon to build and run server code, use a
[hosted server](/servers/hosted). If a server already runs elsewhere and should be
managed through Horizon, register it as an [external server](/servers/external).

## User-visible contract

A remix server is a composed Horizon MCP endpoint. Clients discover one manifest
and call one server URL. Behind that URL, Horizon routes each selected
capability to the backend server that owns it.

A remix is not a copy of the backend servers, and it does not make backend
servers share runtime state. It is a governed composition layer for MCP
capabilities.

| Concern           | Contract                                                                                                |
| ----------------- | ------------------------------------------------------------------------------------------------------- |
| Client URL        | One Horizon MCP endpoint represents the composed surface.                                               |
| Manifest          | Clients see the selected, namespaced capabilities exposed by the remix.                                 |
| Access            | The remix has its own server access and capability policies.                                            |
| Routing           | Horizon forwards each call to the backend that owns the selected capability.                            |
| Backend ownership | Each backend still owns its implementation, runtime, logs, and application behavior.                    |
| Failures          | A failing backend affects the capabilities routed to that backend, not the meaning of the entire remix. |

<Info>
  Granting a user access to a backend server does not automatically grant access
  to a remix that includes it. The remix is its own Horizon server with its own
  access settings.
</Info>

## Ownership boundary

A remix separates the endpoint clients use from the backend servers that
implement each capability. Keep those responsibilities distinct when you design
the surface, grant access, or debug a failed call.

<CardGroup cols={3}>
  <Card title="Horizon" icon="route">
    Manages the remix URL, stored manifest, namespacing, routing, request logs,
    session records, access checks, and remote credential flow for selected
    external backends.
  </Card>

  <Card title="Remix owner" icon="sliders">
    Chooses the workflow, selects capabilities, grants access, applies
    capability policy, and confirms the composed surface still matches the
    client task.
  </Card>

  <Card title="Backend owner" icon="server">
    Owns the source server, handler behavior, availability, runtime logs,
    schemas, descriptions, compatibility changes, and any policy applied after a
    call reaches the backend.
  </Card>
</CardGroup>

## Design the remix surface

The most important remix decision is not which servers to include. It is which
user task the endpoint should support. Start from the client or agent's job, then
select only the capabilities needed to do that job well.

<CardGroup cols={2}>
  <Card title="Select capabilities, not servers" icon="check">
    Include the specific tools, resources, prompts, and templates the workflow
    needs. Leave unrelated backend capabilities out.
  </Card>

  <Card title="Name for the client" icon="tag">
    Capability names and descriptions are part of the user interface. Make the
    composed manifest clear without requiring users to understand backend
    ownership.
  </Card>

  <Card title="Keep access close to risk" icon="shield-check">
    Use capability policies for sensitive operations, especially writes or
    actions with external side effects.
  </Card>

  <Card title="Keep owners visible" icon="users">
    Make sure each backend has an owner who can respond when its selected
    capabilities fail or change.
  </Card>
</CardGroup>

## How remix works

A remix has two related views of capabilities:

* A stored manifest that Horizon builds when the remix is created or updated.
* Runtime list responses that Horizon produces when a client asks the remix for
  capabilities.

The stored manifest is built from the selected backend capabilities. Horizon
uses it for the dashboard, client setup, and capability policy generation. It is
not the only source used at runtime.

When a client calls `tools/list`, `prompts/list`, `resources/list`, or
`resources/templates/list`, the remix gateway asks the configured backends for
their current lists, namespaces the returned names or URIs, then filters the
results by the remix selection and the caller's capability access.

That means a remix is dynamic enough to reflect backend list responses at
request time, but it is still governed by the capabilities selected for the
remix. A backend can change the schema or description of a selected capability
and the runtime list can reflect that change. A brand-new backend capability is
not exposed just because the backend started listing it; add it to the remix
before clients can use it through the remix endpoint.

Playground, ChatMCP, and external clients call the remix endpoint. They depend on
the runtime gateway being able to reach the selected backends, not only on the
stored manifest existing in Horizon.

<Steps>
  <Step title="Select backends">
    Choose hosted or external MCP servers that should contribute capabilities to
    the remix.
  </Step>

  <Step title="Choose capabilities">
    Include the tools, resources, prompts, and templates that should be exposed
    through the remix endpoint.
  </Step>

  <Step title="Resolve names">
    Horizon keeps backend capabilities distinguishable so clients can call the
    intended tool, resource, prompt, or template.
  </Step>

  <Step title="Configure access">
    Apply server and capability policies to the remix server.
  </Step>

  <Step title="Connect clients">
    Clients use the remix endpoint the same way they use any other Horizon MCP
    endpoint.
  </Step>
</Steps>

## Authentication model

A remix has one client-facing Horizon endpoint, but its backends may have
different authentication requirements. The MCP client authenticates to Horizon
for the remix. Horizon then handles any remote-server credentials needed for
the selected backend capability.

| Backend in the remix             | What the user experiences                                                                                                         | What happens at runtime                                                         |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| Hosted backend                   | No separate backend authorization prompt. The user signs in to Horizon for the remix endpoint.                                    | Horizon routes accepted calls to the hosted backend.                            |
| External backend with OAuth      | If the user has not already authorized that remote server, Horizon asks for remote access before completing client authorization. | Horizon forwards selected calls with the user's stored remote OAuth credential. |
| External backend with token auth | The user must have a stored remote token in Horizon. Token entry happens in Horizon, not through an OAuth redirect.               | Horizon forwards selected calls with the user's stored remote token.            |

The MCP client receives a Horizon credential for the remix endpoint. It does not
receive the remote server's access token, refresh token, or API token.

### OAuth user experience

When a user connects an MCP client to a remix that includes OAuth-backed
external servers, Horizon can pause the client authorization flow until the
user has granted the required remote access.

In that case, the user sees a Horizon authorization page that lists the
external servers needing access. Each server moves from
<code>Needs Access</code> to <code>Authorized</code> after its remote OAuth
popup succeeds. Once all required external servers are authorized, the user can
complete authorization and return to the MCP client.

<Steps>
  <Step title="The client starts Horizon authorization">
    The MCP client opens the Horizon authorization page for the remix endpoint.
    The user signs in to Horizon and Horizon checks access to the remix server.
  </Step>

  <Step title="Horizon checks external backends">
    Horizon checks whether the remix includes external servers that need a
    per-user remote credential. Hosted backends do not add a separate prompt.
  </Step>

  <Step title="Already authorized backends are skipped">
    If the user already has active remote credentials for all required external
    servers, Horizon completes client authorization and redirects back to the
    MCP client.
  </Step>

  <Step title="Missing OAuth access is shown to the user">
    If an OAuth-backed external server needs access, Horizon shows it on the
    authorization page with a <code>Needs Access</code> action. Selecting it
    opens a popup for that remote server's OAuth flow.
  </Step>

  <Step title="Each remote grant completes separately">
    The user approves the requested scopes in the popup. When the popup returns
    to Horizon, that backend is marked authorized. If the remix needs multiple
    external OAuth grants, the user completes them one at a time.
  </Step>

  <Step title="Horizon returns to the client">
    After the required external credentials are active, Horizon finishes the
    original client authorization. The MCP client is connected to the remix
    endpoint, and Horizon uses the stored remote credentials only when calls
    route to those external backends.
  </Step>
</Steps>

### Auth failure behavior

| Event                                                                             | What the user sees                                                                                         | Remix impact                                                                                                                      |
| --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| The user has remix access but has not authorized an OAuth-backed external backend | Horizon shows that backend as needing access before client authorization can complete.                     | The user must authorize the remote backend before using the remix from that client flow.                                          |
| The user closes or denies one backend's OAuth popup                               | That backend remains unauthorized and the completion button stays blocked.                                 | Other successful backend grants remain saved, but the remix authorization is not complete until required backends are authorized. |
| A token-backed external backend has no stored token                               | The user needs to add the token in Horizon.                                                                | Calls routed to that backend cannot authenticate until the token is saved.                                                        |
| A stored remote credential expires or is revoked after the client connected       | Calls routed to that external backend fail authorization until the user reauthorizes or updates the token. | Other backends in the remix are not automatically affected.                                                                       |
| Horizon policy denies the caller or selected capability                           | The user cannot discover or call the denied capability through the remix.                                  | Remote backend authorization does not override Horizon access policy.                                                             |

## Common patterns

<CardGroup cols={2}>
  <Card title="Team workspace" icon="users">
    Combine the approved engineering, support, operations, or documentation
    capabilities a team needs into one client configuration.
  </Card>

  <Card title="Read/write split" icon="shield">
    Expose broad read-only capabilities while restricting write tools to
    narrower roles.
  </Card>

  <Card title="Partner endpoint" icon="handshake">
    Publish a limited set of capabilities for external collaborators without
    exposing every backend server.
  </Card>

  <Card title="Migration layer" icon="arrows-rotate">
    Keep one client endpoint while moving selected capabilities between backend
    servers.
  </Card>
</CardGroup>

For example, a support workflow remix might expose customer lookup, recent
activity search, runbook retrieval, and incident summary creation while leaving
administrative or destructive backend tools out of the manifest. The client gets
one focused server, and backend owners keep their existing servers.

## Changes and failures

A remix has three moving parts that can change independently: the selected
capability set, the backend behavior behind those capabilities, and the caller's
access. When something looks stale or broken, check which part changed before
changing the client configuration.

<CardGroup cols={2}>
  <Card title="Selection changes" icon="sliders">
    New backend capabilities stay hidden until they are selected for the remix.
    Removed or renamed selected capabilities can disappear from the client or
    fail when called.
  </Card>

  <Card title="Schema changes" icon="code">
    Input schema, output shape, and description changes can affect clients even
    when the capability name stays the same.
  </Card>

  <Card title="Access changes" icon="shield">
    Remix access controls discovery and calls through the composed endpoint.
    Backend authorization does not override remix policy.
  </Card>

  <Card title="Backend health" icon="server">
    Outages, remote credential problems, and protocol errors affect the
    capabilities routed to that backend.
  </Card>
</CardGroup>

Runtime list requests fan out to the selected backends. Tool, resource, and
prompt calls are routed by name or URI. In a multi-backend remix, namespacing
keeps backend capabilities distinguishable so the requested capability tells the
gateway which backend should receive the call.

<AccordionGroup>
  <Accordion title="A backend is unavailable during a list request">
    Horizon can return capabilities from reachable backends and omit
    capabilities from the unavailable backend for that list response. If the
    backend returns an authentication, authorization, or protocol error while
    listing, the list request can fail instead of returning a partial list.
  </Accordion>

  <Accordion title="A backend does not support a list method">
    Horizon treats that capability type as empty for that backend. Other
    supported capability types can still appear when their list requests
    succeed.
  </Accordion>

  <Accordion title="A backend adds, removes, or renames a capability">
    A new backend capability stays hidden until the remix is updated to include
    it. A removed selected capability disappears from runtime list responses and
    calls to it fail. Treat a rename as removing the old capability and adding a
    new one because existing clients and policies may reference the old name.
  </Accordion>

  <Accordion title="A selected capability changes schema">
    Existing client calls may become invalid. Test the updated capability in
    Playground before updating clients, and update descriptions when the client
    needs different instructions.
  </Accordion>

  <Accordion title="A caller lacks access to a selected capability">
    The capability is filtered out of list responses and blocked when called
    directly. Updating backend authorization will not grant access through the
    remix if remix policy denies the caller.
  </Accordion>

  <Accordion title="A backend connection or credential changes">
    Calls routed to that backend can fail until the backend connection settings
    or stored remote credentials are updated. Other selected backends are not
    automatically affected.
  </Accordion>

  <Accordion title="A selected capability fails during a call">
    That call fails for the client; calls routed to other backend capabilities
    are not automatically affected. Use remix request logs to identify the
    selected capability and backend, then inspect the backend's runtime logs.
  </Accordion>
</AccordionGroup>

<Info>
  A remix can narrow what clients see, but it does not make sensitive backend
  behavior safe by itself. Treat sensitive backend tools as sensitive even when
  they are exposed through a smaller remix surface.
</Info>

## Before clients use the remix

A remix is ready for client use when its manifest is small enough to be
understandable, its sensitive capabilities are governed, and each selected
backend can be debugged by the team that owns it.

Check the composed endpoint before updating client configuration:

* The remix manifest includes only the capabilities needed for the workflow.
* Capability names and descriptions make sense without knowing which backend
  owns them.
* Playground or ChatMCP can call representative capabilities through the remix
  endpoint.
* Capability policies cover sensitive write actions and external side effects.
* Request logs identify which selected capability and backend handled each call.
* Backend owners know which of their capabilities are exposed through the remix.

These checks keep the remix from becoming a hidden bundle of every useful tool.
The value of a remix is the smaller, clearer surface it gives to clients. If the
manifest is hard to explain, split it by workflow or remove capabilities that do
not belong.

## Troubleshooting

Start with the user's symptom. If a capability is missing, check the manifest,
selection, and capability policy. If a call reached the remix endpoint, use
request logs to identify the selected capability and backend before debugging
the backend runtime.

<AccordionGroup>
  <Accordion title="A backend capability is missing">
    Confirm the backend manifest includes the capability and that the remix
    selected it for exposure. New backend capabilities are not automatically
    exposed through an existing remix.
  </Accordion>

  <Accordion title="A user can access a backend directly but not through the remix">
    Review access on the remix server. The remix has its own server and
    capability policies.
  </Accordion>

  <Accordion title="A user can see the remix but cannot call one capability">
    Check capability policy on the remix. The user may have server access
    without permission for that selected capability.
  </Accordion>

  <Accordion title="The client authorization page says external servers need access">
    The remix includes one or more external servers that require per-user remote
    credentials. The user needs to authorize each OAuth-backed external server
    before Horizon completes the client authorization flow.
  </Accordion>

  <Accordion title="One external backend is authorized but the remix still will not complete">
    Check whether another external backend in the remix still needs access or a
    token-backed backend still needs a stored token. Horizon completes client
    authorization only after the required external credentials are active.
  </Accordion>

  <Accordion title="A backend call fails">
    Check remix request logs first to identify the selected capability and
    backend. Then inspect the backend server's logs or remote runtime depending
    on where that backend runs.
  </Accordion>

  <Accordion title="A capability name is confusing in the client">
    Review backend namespacing and descriptions. Client users usually see the
    remix manifest, so names and descriptions should make the capability's
    purpose clear without exposing backend details.
  </Accordion>

  <Accordion title="A backend changed but the remix did not">
    Refresh or edit the remix so its selected capabilities match the new backend
    manifest.
  </Accordion>
</AccordionGroup>

## Related docs

<CardGroup cols={2}>
  <Card title="External servers" icon="plug" href="/servers/external">
    Register remote MCP servers as backends for Horizon and remix servers.
  </Card>

  <Card title="Authorization" icon="shield" href="/platform/authorization">
    Apply server and capability policies.
  </Card>

  <Card title="Connect a client" icon="plug" href="/connect-a-client">
    Add the remix endpoint to an MCP client.
  </Card>
</CardGroup>