Skip to main content
Tool Gateway is in beta.
Connecting an account stores the credential that Tool Gateway attaches when it calls an MCP server. The credential is an OAuth token, or an API key for a server that expects one in a header. Each credential belongs to one owner. Therefore, the same server can run as a different account for each user, agent, or profile that calls it. For how Tool Gateway picks the owner on each call, see Credential owners. Connect an account after the server is added. A public server needs no credential, so it has nothing to connect. To add a server, see Add MCP servers. The Connected as selector is on Tools > MCP servers, in the Workspace view. The API examples on this page use the environment variables from the quickstart. Managing another owner’s credentials requires a user credential, such as a personal access token, not a service key.

Connect your own account

Connect your own account to call a server as yourself, for example from an MCP client that uses your API key. Each user connects separately, and no one else can use your credential.
  1. Go to Tools > MCP servers.
  2. On the server’s row, click Connect.
  3. Complete the step for the server’s credential type:
    • OAuth: In the tab that opens, approve access with the service. A LangSmith page confirms that authentication succeeded.
    • API key: Enter your key, then click Save and connect.
The server’s status changes to Connected.
You can also connect when you first need to. A tool call on a server you have not connected returns a sign-in link. See Call tools.

Connect an account for an agent

An agent’s credential lets the agent call a server as itself, on calls made with an API key bound to the agent’s environment. Each agent environment holds its own credentials, so an agent’s development and production environments can use different accounts. Connecting for an agent requires the workspaces:credentials:manage permission, plus projects:update on the tracing project of the agent environment.
  1. Go to Tools > MCP servers, and set Connected as to Agent.
  2. Choose the agent, then choose the environment.
  3. On the server’s row, click Connect, and complete the sign-in or enter the API key for the agent.
An agent cannot connect its own credentials. If one is missing, the agent’s tool call returns 409 until an admin connects it.

Connect an account for a profile

A profile is a named set of credentials that an admin connects once, for agents or other callers that run with no one signed in. A caller selects the profile by sending its ID in the X-LangSmith-Profile header. See Act as users and agents. Creating a profile and connecting its credentials require the workspaces:credentials:manage permission. Connecting a server also requires permission to call that server.
  1. Go to Tools > MCP servers, and set Connected as to Profile.
  2. Click Add profile, enter a name, such as Support agent, and click Create profile.
  3. On each server’s row, click Connect, and complete the sign-in or enter the API key for the profile.
To copy the header that selects the profile, click Copy profile header.
A caller that uses a profile cannot connect a missing credential. Its tool call returns 409 until an admin connects one. To rename or delete a profile, use the profile’s actions menu in the UI, or PATCH or DELETE /v1/managed-tools/profiles/<profile-id>. Deleting a profile deletes every credential connected to it and revokes its OAuth tokens with the provider. Agents that use the profile stop working.

Connect one API key for the workspace

A workspace credential is one API key that every caller of a server uses, including agents in the workspace. Use it for a service where everyone shares one account, so that no user needs to connect their own key. Only a workspace server that expects an API key accepts a workspace credential. Setting one requires the workspaces:credentials:manage permission.
Storing a workspace credential permanently deletes every other credential on the server, for every user, agent, and profile. While the workspace credential is stored, no other owner can connect one.
To set the key when you add the server, select API key, set Credentials to Workspace, and enter the key. In the API, include "credential": {"owner_type": "workspace", "fields": {...}} in the POST /v1/managed-tools/servers request. See Add MCP servers. To set or replace the key on a server that already exists, use the API:
A server that does not expect an API key, or is not a workspace server, returns 409.

Disconnect an account

Disconnecting deletes one owner’s credential and keeps the server and every other owner’s credentials. Calls that relied on the credential fail until the owner connects again. Disconnecting revokes OAuth tokens with the provider. To disconnect your own account:
  • UI: On Tools > MCP servers, open the server, then click Disconnect. Do not use the row’s delete action, which deletes the server for everyone.
  • API:
To disconnect another owner, set Connected as to that owner in the UI and click Disconnect on the server’s row. In the API, send the same request with the owner named:
  • An agent: Add ?credential_owner_type=agent_identity&credential_owner_id=<agent-environment-id>.
  • A profile: Send DELETE /v1/managed-tools/profiles/<profile-id>/servers/<server-id>/credential.
  • The workspace: Add ?credential_owner_type=workspace&credential_owner_id=$LANGSMITH_WORKSPACE_ID. Callers then have no credential for the server until they connect their own.
The request returns 204 if the owner is already disconnected. If the server uses Manual OAuth, your credential lives in a shared Agent Auth connection. Disconnecting removes it from every server and integration that uses that connection.

See also