Connecting tools

An MCP tool server is a service outside the platform that offers tools over the Model Context Protocol (MCP): search a code hub, read a calendar, look a customer up in a CRM. Your platform’s operators register a server once. Its tools then appear in the tool catalog as mcp__<server>__<tool>, and any agent whose trust tier allows them can use them. Many servers act as a signed-in person, so before an agent can call them someone has to connect an account.

This page is for operators adding a server, workspace admins setting up shared accounts, and members connecting their own.

Add a server

Operators add servers on the Tools page with Add MCP server. Fill in a Name (it becomes part of every tool name), the server’s URL and its Transport, then choose how the platform signs in under Authentication:

Choice	Use it when
None	The server needs no sign-in.
Static headers	The server takes a fixed API key or token in a header, the same for every caller. Values are write-only: they are never shown again.
OAuth: each person signs in	The server acts as a person (their mail, their files). Each member connects their own account, and an agent acts as whoever is using it.
OAuth: one account per workspace	The server should act as one account the whole workspace shares, such as a team mailbox or a service account. A workspace admin connects it.

Two more settings decide who can use the server’s tools:

• Ask before running, covered under Approvals below.
• Allow untrusted-tier agents to use this server’s tools. Agents created in a workspace are untrusted-tier, so leave this off and they cannot call the server, and members cannot connect an account to it. Turn it on only for a server whose tools you have reviewed.

Test connection tries the settings before you save. For None and Static headers it lists the tools it finds. For an OAuth server there is no account yet, so it shows the authorization server and the scopes it publishes instead.

What you need for OAuth

You register an OAuth app with the server’s provider. The provider gives you a client ID and a secret, and you give it the address it sends people back to:

• Type. A web application with a client secret.
• Redirect URI. The form shows it under Redirect URI, with a Copy button. It has the form https://<your platform's address>/api/manage/mcp/oauth/callback. Register it with the provider exactly as shown.
• Scopes. Enter them in Scopes, separated by spaces. Fetch from server fills in the scopes the server publishes. If the server publishes none, type the ones its provider documents. Left empty, the platform asks for what the server publishes.

Enter the Client ID and Client secret. The secret is write-only. Under Advanced, Authorization server is only for a server that publishes no protected-resource metadata.

Connect for discovery

An OAuth server lists its tools only to a signed-in caller. After saving one, click Connect for discovery in its row and sign in. The platform uses that account only to list the server’s tools, and the Discovery column shows which account it is. Use Refresh in the row menu to list the tools again later.

Saving a new client ID, secret, scopes or authorization server disconnects the discovery account, so connect it again. Saving a new URL also deletes every account connected to the server, because those accounts signed in for the old URL. Switching away from OAuth deletes the OAuth client and every connected account. The form warns you before any of these saves.

Connect your account

When an agent first calls a tool from a per-person server you have not connected, the chat shows a Connect card below the reply. Click Connect, sign in with the provider in the window that opens, then ask the agent to try again. The same card asks you to reconnect when a connection has expired, and it says needs more access when the server wants permissions you did not grant.

You can also manage your accounts ahead of time. Open Account from your account menu. Connected accounts lists every per-person integration with its account, when you connected it and its status, with Connect, Reconnect and Disconnect. Disconnecting asks the provider to revoke the platform’s access, and agents stop using that account until you connect it again.

Whose account a run uses

Run	Each-person server	Workspace server
You, in the console or a chat	yours	the workspace’s
A schedule or webhook	the trigger owner’s	the workspace’s
An API key	none	the workspace’s
A visitor to an embedded agent	none	none
Forge itself	none	none

Inside a workflow, every agent uses the accounts of whoever started the run. Where the table says none, the agent is told the integration isn’t available there.

Shared workspace accounts

Workspace admins manage connections on Tenants, in their workspace’s Connections tab. It lists every integration that signs in with OAuth:

• A workspace server shows the shared account, with Connect or Reconnect. Every agent, workflow and schedule in the workspace uses that one account. Disconnecting it takes the integration away from all of them until an admin connects it again.
• A per-person server shows how many members have connected. Members connect their own accounts on their Account page.

A member who is not an admin sees the chat’s Connect card for a workspace server too, but it asks them to get an admin to connect it.

Use your own OAuth app

By default people sign in through the platform’s own OAuth app for each server. Some organisations allow only apps they registered themselves. An admin can choose Use our own OAuth app… from the integration’s row menu, register an app with the provider under the redirect URI the dialog shows, and enter its client ID and secret. New connections in the workspace then sign in with your app, and the OAuth app column says Your own.

Connections made with the platform’s app keep working. Changing your app, or choosing Stop using our own OAuth app, deletes the connections made with the previous one, so those people connect again.

Approvals

A tool from an outside server can send your conversation’s data somewhere, so by default it asks before it runs. The person in the chat sees the call and chooses Allow, Always allow in this conversation or Deny.

Each server has an Ask before running setting, chosen by the operator:

• Ask unless the tool is read-only (the default). A tool the server marks read-only runs without asking, and every other tool asks. The mark is the server’s own claim.
• Always ask. Every tool asks. An agent’s author cannot exempt a tool on this server, but the person’s own choices in the chat, described below, still apply.
• Never ask. No tool asks unless an agent’s author requires it.

An agent’s author can adjust this per agent in the agent editor:

• Allow without asking, in the editor’s Approval before running list, lets a tool run without asking in every chat, embed and schedule. It has no effect on an Always ask server.
• The shield beside a tool in the agent’s tool list makes it ask whatever the server’s setting says.

The person in the chat can also skip the question, on any server: Always allow in this conversation stops asking about that tool for the rest of the conversation, and the approval mode in the message box applies on top. Ask every time asks as above, Approve for me runs these tools without asking, and Full access, offered in Forge only, also lets Forge’s own changes go ahead without review.

Some runs have nobody to ask:

• An embedded agent’s visitors are asked about every tool that asks. To spare them, use Allow without asking for the tools the agent needs. Visitors cannot connect accounts, and an embedded agent cannot use an OAuth integration at all, per-person or shared.
• Schedules, webhooks and API keys stop at the question. A scheduled run shows as “Waiting for approval or stopped” on the Triggers tab. Allow the tool without asking for that agent, or ask an operator to change the server’s setting.
• A workflow’s tool step calls its tool without asking, because the step’s author wrote the call. It cannot call a tool whose server is set to Always ask, and saving such a step is refused: call that tool from an agent in the workflow instead. A step whose account is missing or expired fails with that message. A step fails too when the server refuses the call or cannot be reached.

Forge

Forge does not use connected accounts. If Forge calls a tool from an OAuth server, it is told so and passes it on: talk to an agent that has the tool. Open the message box’s + menu, choose Talk to and pick the agent. It answers as you, with your connected accounts.

Troubleshooting

• “Unreachable or failed”. The platform could not reach the server or talk to it, and the message gives the cause. Check the URL and that the server is up.
• “Returned an error”. The platform reached the server, but the server refused the call, with its own text after the colon. Reconnecting rarely helps. Check the OAuth app and the API settings on the provider’s side, for example that the API is enabled for the app’s project and that your account may use it.
• Needs more access. The server wants permissions the connection does not have. Reconnect from the card or from Connected accounts, and allow everything the provider asks for. If it keeps asking, the operator may need to add the scope under Scopes.
• Expired. The provider no longer accepts the connection, for example because access was revoked on the provider’s side. Reconnect.
• “This integration isn’t available to your workspace’s agents; ask an operator.” The server is not allowed for untrusted-tier agents, so only an operator can change that.
• Google says it hasn’t verified the app. A Google OAuth app in testing mode shows this warning, and only the test users added to the app can sign in. Add the people who will connect as test users, or have the app verified by Google.
• The provider requires enrollment. Some providers offer their MCP servers only to accounts in a preview or a particular plan. Google’s Workspace MCP servers, for example, are in a Google developer preview: an account outside it can connect, but its calls are refused with “The caller does not have permission”. Check the provider’s requirements before connecting.

Example: Hugging Face

1. On Hugging Face, create an OAuth app at huggingface.co/settings/applications/new. Paste the redirect URI from the Add MCP server form, and choose the scopes openid, profile, email and read-mcp. Keep the client ID and secret.
2. On the Tools page, choose Add MCP server: name huggingface, URL https://huggingface.co/mcp, Authentication set to OAuth: each person signs in, the client ID and secret, and Scopes set to openid profile email read-mcp. Turn on Allow untrusted-tier agents to use this server’s tools if workspace agents should use it. Test connection, then Add server.
3. Click Connect for discovery and sign in to Hugging Face. The row then shows the tools.
4. Add the tools you want to an agent. The first time someone uses one, the chat shows a Connect card. After they connect, they ask the agent to try again.