Link your credential to a Connector

Sign in to the upstream system with OAuth, or paste a token, so a Connector can act as you.

Agentic Friendly

Most Connectors reach their upstream system as the individual calling user. Before you can see or call such a server's tools, you supply your own credential for it. This is called Linking, and every member does it for themselves.

A user registering a server does not link it for anyone else. Sharing an Agent does not share access either. Nobody's credential is ever used on another person's request.

A server whose credential mode is Unauthenticated is the exception. It has no credential to link, and nothing on this page applies to it. See Servers that need no account.

Two routes to the same result

RouteYou do thisUse it when
OAuth LinkingSign in to the upstream system in a browser and approve accessThe Connector supports OAuth. Most hosted services do
Paste a credentialCreate a token in the upstream system and paste itThe server takes a personal access token or API key

Both end in the same encrypted record, and nothing downstream can tell which route you took. The Portal offers both, and you can switch between them at any time by linking again.

  1. Open Connectors in the Portal sidebar and select the server.
  2. Find the credential card. It reads One more step: link your credential until you link, and Your credential afterwards.

An unlinked server shows both options.

Linear (read-only) MCP Server with an unlinked credential, offering Link with OAuth or Paste a User Credential instead

With OAuth

  1. Select Link with OAuth. The Portal sends you to the upstream system's sign-in page.
  2. Sign in and approve access.
  3. The upstream system returns you to the Portal, which finishes the link and confirms it.

Behind the sign-in page, unless an administrator entered an app registration on the Connector, the platform discovers the upstream authorization server from the Connector itself and registers itself as a public client the first time anyone in your organization links that server. That registration belongs to the organization and the server, not to you, and carries no secret. In that case the platform requests no scopes of its own, and what you are granted is what the upstream system decides to grant, on the consent screen you see.

Some providers, such as Microsoft and Slack, need an app that an administrator registers with them. On such a Connector you sign in through the administrator's app, at the authorization server the administrator named, and you are asked to grant the scopes the administrator configured. Either way, the exchange is protected with PKCE.

Each attempt is valid once and for ten minutes. If you leave the flow and come back, or the exchange fails, start again from the server. There is no retry, because the attempt is spent.

If you decline at the upstream system, the Portal says the linking was canceled and that nothing changed.

By pasting a credential

  1. Create the token in the upstream system. A GitHub personal access token and an Atlassian API token are typical examples.
  2. Select Paste a User Credential instead.
  3. Paste the value and select Link it.

Dialog for pasting a User Credential with a masked input

The field takes up to 4096 characters and rejects an empty or whitespace-only value. It is never prefilled and never shown back to you.

The value is not checked against the upstream system when you paste it. A wrong or expired token is reported the first time you call the server.

Servers that need no account

Some Connectors reach an upstream system that has no account of its own. Context7 is one. A user with mcp.server.create registers such a server with the Unauthenticated credential mode, and the MCP Gateway sends it no Authorization header.

You link nothing to an unauthenticated server, and you do not have to. Linking is not a step between you and its tools, in chat, in an Agent, or from an external MCP client. What remains is the server itself: a Managed workload still has to be ready, and a Remote endpoint still has to answer.

The Portal shows the mode instead of a credential card. The server list marks the row Unauthenticated rather than Not linked, and the detail page replaces the credential card with a note that the upstream needs none.

An attempt to link a credential anyway is refused with mcp_server_needs_no_credential. Do not paste a placeholder token: there is nowhere to put it, and an unauthenticated upstream never asked for one.

If an unauthenticated server reports that your credential was refused, the upstream system wants authentication after all and the server's credential mode does not match it. Ask a user with server-delete and server-create permissions to re-add the server so each user links their own credential. Nothing you link can fix it from your side.

Check what you have linked

The server list has a Your credential column reading Linked, Not linked, or Unauthenticated. The first two are yours alone and say nothing about anyone else. The third is a property of the server and reads the same for everyone.

An unlinked row explains that the server's tools are hidden from you until you open it and link one.

The detail page distinguishes a credential that has been linked but not yet used from one already in use.

Replace or remove a credential

Linking again replaces what you have. The credential it replaces stops working at once. The Portal asks you to confirm.

Unlink removes your credential from that server. Your calls through the MCP Gateway fail until you link it again. Unlinking affects only you.

Deleting a Connector removes every User Credential linked to it.

What happens to the credential

Your credential is encrypted before it is stored, with a key held by the deployment and a separate derivation per user and per server. No endpoint returns it, in any form, to you or to anyone else.

The MCP Gateway decrypts it only while forwarding a request you made, and supplies it to the Connector in place of your platform credential. Your platform token or API key never reaches a Connector or an upstream system.

An OAuth credential is renewed on use. When the access token is close to expiry, the platform refreshes it just before the call, so a link keeps working without you doing anything. A pasted token has no expiry and is never refreshed.

If an administrator changes the client ID or the authorization server of the Connector's app registration, or adds or removes the app registration, your OAuth link is no longer renewed. It keeps working until its current access expires, and then you link again.

When a call fails

MessageCauseWhat to do
No credential is linked for this ConnectorYou have not linked this serverLink it
The credential linked for this Connector was refusedThe upstream system rejected it. It was revoked, or it never had accessLink it again
The credential linked for this Connector has expiredAn OAuth link the platform could no longer renewLink it again with OAuth
Sign-in was cancelled or refused at the provider, so nothing was linkedYou canceled, or the provider requires an approval you cannot giveLink again. If the provider asks for an administrator's approval, ask your administrator
The sign-in provider rejected the administrator's app configurationThe provider refused the Connector's app registration, while linking or while renewing your linkAsk an administrator to check the app's client ID, client secret, and permissions. An existing link stays in place
The OAuth client cannot be usedThe Connector's app registration is not validAsk an administrator to correct it
The stored client secret of this Connector's app registration could not be readThe platform cannot read the client secret an administrator stored on the ConnectorAsk an administrator to enter the client secret again
This Connector does not use OAuthThe server presented no OAuth challengePaste a credential instead
OAuth Linking is not configured for this deploymentThe deployment has not published an OAuth return addressPaste a credential instead, or ask the platform operator to configure it
This MCP Server is unauthenticated and takes no User CredentialThe server's credential mode is UnauthenticatedNothing. Its tools already work for you

A refused credential and an expired one are different problems. A refusal means the upstream system said no to the value you linked. An expiry means the link is dead and only signing in again revives it.

Using a linked server in chat

A server contributes tools to a conversation once you can reach it: either you have linked it, or it is unauthenticated and needs no link. The rest are absent, whether you turned them on yourself or an Agent requires them. Chat tells you when an Agent needs a server you have not linked and offers to link it. It says nothing about an unauthenticated server, because there is nothing to fix.

See Use a Connector in chat for turning connectors on and reading a tool call.

The Agent editor marks a server the editor has not linked and reminds whoever builds the Agent that every member has to link the servers themselves. It raises neither for an unauthenticated server, which nobody links.

export BSQAI_TOKEN=sk-bsq-v1-...
export SERVER_ID="<server-id>"

curl -X PUT "https://api.<platform-domain>/v1/mcp/servers/$SERVER_ID/credential" \
  -H "Authorization: Bearer $BSQAI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"credential": "<your upstream token>"}'

A successful link answers 204 with no body. Remove it with the same path and DELETE.

Against an unauthenticated server, PUT answers 400 with mcp_server_needs_no_credential and stores nothing, and POST /v1/mcp/servers/{server_id}/credential/oauth answers the same unless the deployment publishes no OAuth return address, which it reports first. DELETE still answers 204, so a client clearing its credentials does not have to special-case the mode.

Read your own link state from GET /v1/mcp/servers/{server_id}, which reports credential_mode, linked, and credential_last_used_at. An unauthenticated server reports linked: false for everyone, permanently, because nobody links one. Read credential_mode before linked.

On this page