Skip to navigation

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:

{
"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:

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

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.

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.

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:

ToolWhat it does
search_toolTakes 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_toolTakes a tool name from the search results. Returns that tool’s description and input schema.
execute_toolTakes 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:

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:

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 seeWhat it means
401 with the body UnauthorizedThe gateway key is missing or wrong. Check the fg-api-key header.
401 with a WWW-Authenticate headerThe route uses JWT Auth. Sign in as described in Authenticate by signing in.
404The 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.
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 linkThe server needs your own account. See Connect your accounts to MCP servers.

For more error responses, see Handle errors and retries.

Next steps