> 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 server

> Create an MCP server connection, add upstreams, and set the access mode.

An MCP connection exposes an MCP server's tools and resources to agents through a gateway route. This topic shows you how to create an MCP connection, add upstreams, and set the access mode.

## Prerequisites

Before you begin, make sure you have the following:

* Access to a Fabric AI Gateway organization, with permission to create connections.
* The target URL of the MCP server. For a shared credential, also have the API key or token that the server requires.

## Create an MCP connection

To create an MCP connection, do the following:

1. In the sidebar, select **MCP servers**.
2. To connect a server from the catalog, select the **Providers** tab, and then select **Connect** next to the server. To connect any other server, select the **Connections** tab, select **Create connection**, and then for **Provider**, select **Custom server**. The **Create MCP connection** page opens.
3. In **Connection**, enter a **Connection name**, for example `linear-mcp`. For a custom server, also enter the **Target URL**, for example `https://mcp.linear.app/mcp`. Leave **Access** set to **Open**, or select **Gated**. For details, see [Set the access mode](#set-the-access-mode).
4. In **Upstream auth**, select the **Auth type** that the server expects. For a custom server, the choices are **API key**, **Bearer token**, **OAuth**, and **None**. For **API key**, also enter the **Header** that the server reads the key from. The default is `x-api-key`. For **Credential**, keep **Per-user** so that each person uses their own credential, or select **Shared** to use one credential for the whole organization. With **OAuth**, the credential is always **Per-user**:

   * **Shared** with **API key** or **Bearer token**: enter the key or token now. If your organization runs its own data plane, enter a vault reference instead.
   * **Per-user**, and the only option with **OAuth**: each person connects their own account the first time they use the server.

   > **Note**
   >
   > On this form, **OAuth** works only with MCP servers that publish OAuth discovery metadata. Fabric uses the metadata to find the server's authorization server and register with it. Each person signs in the first time they use one of the server's tools. Until then, they see a `connect_<name>` tool or a sign-in prompt for the server. For the caller's side, see [Connect your accounts to MCP servers](/use/mcp/connect-your-accounts).
5. In **Gateway route**, keep **Create gateway route** selected. Review the **Route name** and the **Path**, which defaults to `/mcp/` followed by the connection name. Keep **Gateway auth** set to **Gateway key**, so callers must send a gateway key in the `fg-api-key` header. To create a key for your callers now, select **Create key**. For details, see [Authenticate requests with Key Auth](/configure/authentication/key-auth).
6. Select **Create connection**. Fabric creates the connection and the route, and opens the connection's page.

The connection's page has the tabs **Overview**, **Upstream**, **Routes**, **Plugins**, and **Access**. To change a setting later, open the tab, and then select **Edit** next to the setting.

## Add upstreams

An MCP connection can point to one or more upstreams. The gateway treats each upstream as a separate MCP server. It lists the tools from every upstream as one set, and sends each tool call to the upstream that provides that tool. If two upstreams provide a tool with the same name, the gateway uses the one from the upstream listed first.

To add an upstream, do the following:

1. On the connection's page, select the **Upstream** tab.
2. Next to **Upstreams**, select **Edit**.
3. Select **Add upstream**, and then enter a **Target URL** and a **Name** for the upstream.
4. Select **Save**.

The **Load balancer** setting and upstream weights don't apply to MCP tool calls. To spread traffic across copies of one MCP server, put your own load balancer in front of them, and add its address as a single upstream.

## Set the access mode

The connection's **Access** setting decides whether callers need a grant:

| Access mode | Behavior                                                                                        |
| ----------- | ----------------------------------------------------------------------------------------------- |
| **Open**    | Anyone who passes gateway auth can call the connection.                                         |
| **Gated**   | Only callers with a grant can call the connection. Callers without a grant don't see its tools. |

To change the access mode, select **Edit** next to **Access** on the **Overview** tab. The **Access** tab is available only when **Access** is **Gated**. To add grants to a gated connection, select the **Access** tab, and then select **Add grant**. For more information about access modes, see [Manage connections and routes](/configure/connections#set-the-access-mode).

## Next steps

* To rate limit an MCP route or add other policies, see [Control traffic with plugins](/configure/plugins).
* To keep a large set of tools from filling a model's context, add the [**Tool Search** plugin](/reference/plugins/tool-search) to the MCP route. It gives the model three tools (search, get, and execute) that find the others.
* To review MCP traffic, see [Review analytics](/use/monitor/analytics).