Connect an MCP client to an MCP route
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.
- 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.
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.
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:
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:
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:
- Add the route URL to your client, with no
fg-api-keyheader. - Connect. The gateway answers
401 Unauthorizedwith aWWW-Authenticateheader that points the client at the route’s sign-in details. - Your client registers itself and opens your browser.
- Sign in with your organization’s identity provider.
- Return to your client. It now sends a bearer token in the
Authorizationheader 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).
The gateway doesn’t refresh this token. When it expires, the client gets a 401 again and asks you to sign in again.
JWT Auth is available only when your organization runs its own data plane. For details, see Choose a deployment model.
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.
- 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.
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, 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:
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:
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:
The result lists the route’s tools, or the three tool search tools.
If something fails, check the following:
For more error responses, see Handle errors and retries.
Next steps
- Connect your own account to a server that needs it. See Connect your accounts to MCP servers.
- Learn how the gateway handles each request. See Follow a request through the gateway.
- Review your MCP traffic. See Review analytics.

