Skip to navigation

Connect your accounts to MCP servers

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.
  • 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:

WhereWhat you see
Tool listA tool named connect_<name> appears in place of that server’s tools. When the model or you call it, it returns a link.
Tool callThe call fails with JSON-RPC error -32001. The error message contains the link.
Client promptClients that support URL elicitation show a prompt with the link instead of a connect_ tool.
Other requestsA 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.

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:

CaseWhat happens
The token expired and has no refresh token, or the refresh failedYou get a new link or connect_ tool.
Your admin changed how the connection authenticatesThe old credential is no longer used, and you get a new link.
You revoked the token at the serviceCalls 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 seeWhat to do
403 when you open the linkThe link expired or belongs to another organization. Trigger a new one from your client.
An error page after you sign inThe 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_unavailableThe 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.

Next steps