> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.fabricgateway.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.fabricgateway.ai/_mcp/server.

# Connect an MCP client to an MCP route

> Point an MCP client at an MCP route, authenticate with a gateway key or by signing in, and check that the client sees the route's tools.

An MCP route gives your MCP client one URL for one or more MCP servers. The client talks to the gateway as if it were a single MCP server, and the gateway calls the servers behind the route for it. This topic shows you how to find the route's URL, authenticate your client, find tools on a route that uses tool search, and check that the connection works.

## Prerequisites

Before you begin, make sure you have the following:

* The URL of an MCP route, or access to the console to copy it. Your admin creates the route. For details, see [Connect an MCP server](/configure/connections/mcp-servers).
* A way to authenticate. Either a gateway key for the route, or, if the route uses JWT Auth, an account with your organization's identity provider. Ask your admin which one the route uses.
* An MCP client that supports the Streamable HTTP transport, such as Claude Code, Cursor, or the MCP Inspector.

> **Warning**
>
> Treat gateway keys as secrets. Don't commit them to a repository or share them in screenshots. If a key leaks, rotate it in **Credentials**, or ask your admin to rotate it.

## Get the route URL

The route URL is the data plane host followed by the route's path, for example `https://GATEWAY_HOST/mcp/linear-mcp`. To copy it, in the console sidebar, select **MCP servers**, select the **Routes** tab, find the route, and then select the **Copy DP URL** icon in its row. If you don't have access to the console, ask your admin for the URL.

For a Postman-hosted data plane, the host is a subdomain of `dp.fabricgateway.ai`. Copy it from the console rather than typing it. If your organization runs its own data plane, the host is the one your admin set for it.

## Choose the transport

The gateway speaks the MCP Streamable HTTP transport. Your client sends each JSON-RPC message as a `POST` to the route URL. It can also open a long-lived `GET` stream with `Accept: text/event-stream` on the same URL, over which the gateway tells the client when the tool list changes, for example after you connect an account. On `2026-07-28`, the gateway doesn't serve this stream and answers the `GET` with `405`. Clients on that version receive these notifications through `subscriptions/listen` instead.

The gateway accepts the MCP protocol versions `2024-11-05`, `2025-03-26`, `2025-06-18`, `2025-11-25`, and `2026-07-28`. Your client negotiates the version itself, so you don't need to set it. On `2026-07-28`, some gateway error codes differ from earlier versions. For details, see [Handle errors and retries](/use/errors-and-retries#errors-on-mcp-routes).

In your client's configuration, select the HTTP or Streamable HTTP transport, not SSE or stdio. You don't run a local server process, because the gateway is the server.

## Authenticate with a gateway key

If the route uses Key Auth, send your gateway key in the `fg-api-key` header on every request. Most clients let you add a header to an HTTP server entry. For example, many clients accept a JSON entry like the following:

```json
{
  "mcpServers": {
    "linear": {
      "type": "http",
      "url": "https://GATEWAY_HOST/mcp/linear-mcp",
      "headers": {
        "fg-api-key": "GATEWAY_KEY"
      }
    }
  }
}
```

The gateway removes `fg-api-key` before it calls the MCP server, and adds the server's own credentials itself. You don't send the MCP server's API key or token.

Claude Code needs `"type": "http"` in the entry, as shown. To add the server from the command line instead, run the following:

```bash
claude mcp add --transport http linear https://GATEWAY_HOST/mcp/linear-mcp --header "fg-api-key: GATEWAY_KEY"
```

## Authenticate by signing in

If the route uses JWT Auth, you sign in through your browser instead of pasting a key. Clients that support MCP authorization handle the flow for you:

1. Add the route URL to your client, with no `fg-api-key` header.
2. Connect. The gateway answers `401 Unauthorized` with a `WWW-Authenticate` header that points the client at the route's sign-in details.
3. Your client registers itself and opens your browser.
4. Sign in with your organization's identity provider.
5. Return to your client. It now sends a bearer token in the `Authorization` header on each request.

To check a route's sign-in setup yourself, read the `resource_metadata` URL in the `WWW-Authenticate` header of the `401` response. It has the form `https://GATEWAY_HOST/.well-known/oauth-protected-resource/ROUTE_PATH`. It answers only on routes that use JWT Auth, and returns `404` on other routes. The document names the authorization server that your client signs in with. When the gateway is the authorization server itself, it supports only the authorization code flow with PKCE (`S256`).

```bash
curl "https://GATEWAY_HOST/.well-known/oauth-protected-resource/mcp/linear-mcp"
```

The gateway doesn't refresh this token. When it expires, the client gets a `401` again and asks you to sign in again.

> **Note**
>
> JWT Auth is available only when your organization runs its own data plane. For details, see [Choose a deployment model](/evaluate/deployment-models).

If your client doesn't support MCP authorization, ask your admin for a route that uses Key Auth, and a gateway key for it.

## Understand the tool list

The client sees one tool list for the whole route:

* On a route with one connection, tools keep the names the MCP server gives them.
* On a route with several connections, each tool name starts with a short prefix for its connection, followed by two underscores, for example `gh__search_issues`. The prefix keeps tool names unique across servers.
* You see only the tools that you're allowed to call. Your admin controls this with each connection's **Access** setting and its grants. For details, see [Set the access mode](/configure/connections/mcp-servers#set-the-access-mode).
* A tool named `connect_<name>` means that the server behind it needs you to connect your own account first. For the steps, see [Connect your accounts to MCP servers](/use/mcp/connect-your-accounts).

The gateway builds the list again on each request, so a server that is down drops out of the list until it recovers.

## Find tools with tool search

If the route has the [Tool Search plugin](/reference/plugins/tool-search), the tool list contains exactly three tools instead of the servers' tools. This keeps a large catalog out of the model's context. If you see every tool instead of three, ask your admin to check the Tool Search plugin's embedder settings. The model uses the three tools in the following order:

| Tool           | What it does                                                                                                                                                                                               |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `search_tool`  | Takes a `query` in plain language and an optional `limit`. Returns the best-matching tools with a short summary and a score. It also suggests `connect_` tools for servers that you haven't connected yet. |
| `get_tool`     | Takes a tool `name` from the search results. Returns that tool's description and input schema.                                                                                                             |
| `execute_tool` | Takes the tool's `name` and an `arguments` object. Calls the tool and returns its result.                                                                                                                  |

Search only returns tools that you're allowed to call. You don't need to configure anything in the client: the model reads the three tools' descriptions and calls them like any other tool.

## Verify the connection

To check the route without a client, send an `initialize` request with cURL. Replace `ROUTE_URL` and `GATEWAY_KEY`:

```bash
curl -i "ROUTE_URL" \
  -H "fg-api-key: GATEWAY_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'
```

A successful request returns `200 OK` with an `Mcp-Session-Id` response header and a JSON-RPC result. To list the tools, send `tools/list` with that session ID:

```bash
curl "ROUTE_URL" \
  -H "fg-api-key: GATEWAY_KEY" \
  -H "Mcp-Session-Id: SESSION_ID" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
```

The result lists the route's tools, or the three tool search tools.

If something fails, check the following:

| What you see                                   | What it means                                                                                                                                                                                                                                                                    |
| ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401` with the body `Unauthorized`             | The gateway key is missing or wrong. Check the `fg-api-key` header.                                                                                                                                                                                                              |
| `401` with a `WWW-Authenticate` header         | The route uses JWT Auth. Sign in as described in [Authenticate by signing in](#authenticate-by-signing-in).                                                                                                                                                                      |
| `404`                                          | The URL doesn't match a route in your key's namespace. Copy the URL again from the console, and check that your key comes from the route's namespace. For details, see [Understand how your key picks a namespace](/use/authenticate#understand-how-your-key-picks-a-namespace). |
| JSON-RPC error `-32004`, "tool not authorized" | You aren't allowed to call that tool. Ask your admin for access.                                                                                                                                                                                                                 |
| JSON-RPC error `-32001` with a link            | The server needs your own account. See [Connect your accounts to MCP servers](/use/mcp/connect-your-accounts).                                                                                                                                                                   |

For more error responses, see [Handle errors and retries](/use/errors-and-retries).

## Next steps

* Connect your own account to a server that needs it. See [Connect your accounts to MCP servers](/use/mcp/connect-your-accounts).
* Learn how the gateway handles each request. See [Follow a request through the gateway](/concepts/life-of-a-request).
* Review your MCP traffic. See [Review analytics](/use/monitor/analytics).