> ## 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.

# Connect a client

> Point Claude Desktop, Cursor, ChatGPT, or any MCP client at your Horizon server.

A Horizon server is an MCP endpoint over
[Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http).
Connecting any client comes down to two things: the **server URL** and **how the
client authenticates**. Once a client has both, it discovers the server's tools,
resources, and prompts and can call them.

Every hosted server has a stable URL ending in `/mcp`, shown on its
[Deployments](/deployments) page, of the form
`https://<server-name>.fastmcp.app/mcp`. The examples below use
`https://weather-mcp.fastmcp.app/mcp`; substitute your own.

Horizon's dashboard generates ready-to-paste configuration for each supported
client. Open a server, choose **Connect**, and pick your client to get the exact
snippet with your URL and any required credentials already filled in. This page
explains what those snippets contain so you can read, adapt, and troubleshoot
them.

## Authentication

How a client proves its identity depends on the server's authentication mode and
on what the client supports. For the full model, see
[Authentication](/platform/authentication).

A server with **Horizon authentication enabled** requires every caller to
authenticate, and there are two ways a client does so:

* **Interactive sign-in.** Clients that support authenticated MCP connections
  open a Horizon sign-in flow the first time they connect. The user signs in,
  and the client holds the resulting credential. This is the smoothest path for
  desktop and CLI clients that prompt for authorization.
* **API key.** Clients that cannot sign in interactively send a Horizon
  [API key](/api-keys) as a bearer token. Keys start with `fmcp_` and go in the
  `Authorization` header:

  ```http theme={null}
  Authorization: Bearer fmcp_...
  ```

A server with **Horizon authentication disabled** applies no Horizon access
check, so a public server needs no credential and a server that implements its
own authentication expects whatever its code requires. The rest of this page
shows configuration for a server with Horizon authentication enabled; when it is
disabled, omit the Horizon credential or supply the one your server expects.

## Desktop clients

Claude Desktop and Cursor read MCP servers from a JSON config. Add your server
under `mcpServers` with its URL. Include an `Authorization` header only when the
server needs an API key; clients that sign in interactively leave it out.

For **Claude Desktop**, open **Settings → Developer → Edit Config**, add the
server, and restart Claude:

```json theme={null}
{
  "mcpServers": {
    "weather-mcp": {
      "url": "https://weather-mcp.fastmcp.app/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer fmcp_..."
      }
    }
  }
}
```

For **Cursor**, the config is the same shape without the `transport` field:

```json theme={null}
{
  "mcpServers": {
    "weather-mcp": {
      "url": "https://weather-mcp.fastmcp.app/mcp"
    }
  }
}
```

Cursor also accepts a one-click install link. The **Connect** dialog generates a
`cursor://` deeplink that adds the server without editing config by hand.

## CLI clients

Command-line clients add a server with a single command. Each takes a name, the
URL, and the HTTP transport, and accepts `--env` flags for values your client
passes through.

**Claude Code** authenticates interactively: run the command, then type `/mcp`
in Claude Code to complete sign-in.

```bash theme={null}
claude mcp add --scope local --transport http weather-mcp https://weather-mcp.fastmcp.app/mcp
```

**Gemini CLI**:

```bash theme={null}
gemini mcp add weather-mcp https://weather-mcp.fastmcp.app/mcp --transport http
```

**Codex**:

```bash theme={null}
codex mcp add --url https://weather-mcp.fastmcp.app/mcp weather-mcp
```

## ChatGPT

ChatGPT connects to MCP servers from its web interface rather than a config file.
Enable **Developer mode** in settings, create a new app, choose **OAuth** for
authentication, and paste your server URL into the **MCP Server URL** field.
ChatGPT then runs the Horizon sign-in flow and authorizes the requested
permissions.

## When a connection fails

A failed connection usually stops at the gateway before reaching your server
code. The status tells you where:

<AccordionGroup>
  <Accordion title="401 Unauthorized">
    The client sent no credential, an unsupported `Authorization` scheme, or an
    expired, revoked, or malformed token. Confirm the client is signed in, or
    that the API key is current and sent as `Authorization: Bearer fmcp_...`. See
    [Authentication](/platform/authentication).
  </Accordion>

  <Accordion title="403 Forbidden">
    The caller authenticated, but access settings do not allow them to use the
    server or the requested capability. Check organization membership, server
    access, and capability policy in [Authorization](/platform/authorization).
  </Accordion>

  <Accordion title="404 Not Found">
    The URL maps to no live server, or Horizon is concealing a server from a
    caller without discovery access. Confirm the URL on the
    [Deployments](/deployments) page and the caller's access.
  </Accordion>

  <Accordion title="The client connects but tools are missing">
    Some clients cache the server's tool list. Reconnect or refresh the client's
    capabilities. If a tool is still absent, confirm the live deployment selects
    the build whose manifest contains it.
  </Accordion>
</AccordionGroup>