> 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 your accounts to MCP servers

> Connect your own account on an upstream service, such as GitHub or Atlassian, so the gateway can call that service's MCP server for you.

Some MCP servers act for a specific person, so each user has to connect their own account before the gateway can call them. Your admin decides this per connection. When a server needs your account, the gateway gives your client a link. You open it in a browser, sign in to the service or paste a token, and the gateway stores the credential for you. After that, the gateway adds your credential to every call it makes to that server for you. This topic shows you how to recognize a connect request, connect your account, and what to do when the connection stops working.

## Prerequisites

Before you begin, make sure you have the following:

* An MCP client connected to an MCP route. For the steps, see [Connect an MCP client to an MCP route](/use/mcp/connect-a-client).
* An account on the upstream service, for example GitHub or Atlassian.
* A gateway identity that is yours: your own gateway key, or a sign-in through JWT Auth. The gateway stores the credential for the identity that you authenticate with.

## Recognize a connect request

Your client learns that a server needs your account in one of the following ways:

| Where          | What you see                                                                                                             |
| -------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Tool list      | A tool named `connect_<name>` appears in place of that server's tools. When the model or you call it, it returns a link. |
| Tool call      | The call fails with JSON-RPC error `-32001`. The error message contains the link.                                        |
| Client prompt  | Clients that support URL elicitation show a prompt with the link instead of a `connect_` tool.                           |
| Other requests | A request to a REST or LLM route returns `401` with `"error": "upstream_auth_required"` and the link in `authorize_url`. |

With tool search on, `search_tool` lists the `connect_` tools as suggestions next to its results.

## Connect an account

To connect your account, do the following:

1. Open the link in a browser within 5 minutes. After that, it stops working.
2. Complete the page that opens. What you see depends on how your admin set up the connection:
   * **Sign in with OAuth.** The page sends you to the service's sign-in page, or to your organization's identity provider. Sign in and approve the access that it asks for.
   * **Paste a token.** The page shows a form. Paste the API key or token for the connection, and then submit it. If the gateway sends the value in the `Authorization` header, paste the token only, without a `Bearer` prefix.
   * **Username and password (HTTP Basic).** You can't complete these connections from the link. The page answers `400` and says so. Ask your admin to create the credential in the console.
3. When the success page appears, return to your client.

If your client keeps the gateway's notification stream open, the tool list refreshes by itself. Otherwise, reload the tools or reconnect the MCP server in your client. The `connect_` tool disappears and the server's own tools take its place.

> **Warning**
>
> Treat the link like a password. Anyone who opens it within 5 minutes can connect an account to your identity. Don't paste it into shared chats or tickets.

## Understand what the gateway stores

The gateway stores the credential in your organization's secret store, under your identity and that connection. It never returns the credential to your client, and it never sends it to the control plane. Other users of the same route connect their own accounts separately.

Some connections use one account for the whole organization instead of one per user. If such a connection isn't set up yet, the link connects the organization's account. Ask your admin before you connect one.

## Keep the connection working

OAuth connections that come with a refresh token renew by themselves shortly before they expire. Pasted tokens don't expire on the gateway's side and stay in use until you replace them.

You need to connect again in the following cases:

| Case                                                              | What happens                                                                 |
| ----------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| The token expired and has no refresh token, or the refresh failed | You get a new link or `connect_` tool.                                       |
| Your admin changed how the connection authenticates               | The old credential is no longer used, and you get a new link.                |
| You revoked the token at the service                              | Calls fail with the service's own `401`. Connect again to replace the token. |

To replace a credential, open a new link from your client and connect again. The new credential overwrites the old one.

You can't disconnect an account from the gateway yourself. To stop the gateway from using your account, revoke its access at the service, for example in the service's settings for authorized applications.

## If connecting fails

| What you see                                                                                                                                                                                                       | What to do                                                                                                                                                                                                                                                    |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `403` when you open the link                                                                                                                                                                                       | The link expired or belongs to another organization. Trigger a new one from your client.                                                                                                                                                                      |
| An error page after you sign in                                                                                                                                                                                    | The service or the gateway couldn't complete the sign-in. Start again from your client with a new link.                                                                                                                                                       |
| `503` with `"error": "upstream_auth_unavailable"` on REST routes. On MCP routes, HTTP `200` with JSON-RPC error `-32002` (or `-32012` on protocol revision 2026-07-28) and `data.type` `upstream_auth_unavailable` | The gateway couldn't get your credential right now, for example because its secret store is still loading or a token refresh failed. Wait a few seconds and retry. The response includes `Retry-After: 5`. If it keeps happening, connect your account again. |

For other errors, see [Handle errors and retries](/use/errors-and-retries).

## Next steps

* To learn how admins set up per-user credentials, see [Manage credentials and vaults](/configure/credentials).
* To see where the credential is added to a request, see [Follow a request through the gateway](/concepts/life-of-a-request).