Skip to main content

Connect an MCP Server

Connect your own MCP server and its tools join the shared catalog described in Tools and Agents.

Open MCP Servers in the portal. A tenant's page holds the servers only that tenant can use. Under Manage platform you connect a platform-owned server, which can be shared with tenants.

Connect a server​

Select Connect external MCP and fill in:

  • Name — the internal name of the server. 3 to 63 characters, using lowercase letters, digits and hyphens. It cannot start with rag-, and it cannot be changed later.
  • Display name — an optional label, shown in the portal and in tool pickers.
  • Server URL — the streamable HTTP endpoint of your MCP server. It must use https.

Then select Test connection. The platform contacts the server and fills in the protocol and authentication settings it finds. Select Configure manually to enter them yourself.

Authentication​

Authentication decides how the platform reaches your server:

  • None — the server accepts requests without credentials.
  • API key — the platform sends the key you enter as a bearer token.
  • OAuth — each user signs in to the server themselves. Fill in the authorization URL and the token URL, or leave both blank to let the platform discover them from the server's metadata. Add the OAuth callback URL shown in the form to the allowed callback URLs of the OAuth application.

Authorization parameters​

Some providers need extra values in the sign-in request, such as an audience or a tenant. Add them under Authorization parameters as pairs of Parameter name and Parameter value. Select Add parameter for each pair.

Every name must be filled in, and each name can be used only once. Values are sent exactly as you type them, including commas, equals signs and spaces.

These names belong to the OAuth protocol itself and are refused: state, code, scope, resource, client_id, redirect_uri, response_type, code_challenge, code_challenge_method. Use the Scopes and Resource / audience fields for the first two of those.

Custom headers​

Some servers expect a fixed header on every request, for example their own API-key header. Add them under Custom headers as pairs of Header name and Header value, one pair per header. Select Add header for each pair.

Header values are write-only. The platform stores a value and never shows it again, so the server's page lists only the header names.

A header is refused when:

  • the name or the value is empty;
  • the name uses characters that are not allowed in an HTTP header name;
  • the same name is used twice — upper and lower case count as the same name;
  • the name starts with mcp-, or is Accept, Content-Type, Connection, Last-Event-ID, MCP-Session-Id, Transfer-Encoding or Upgrade. The platform sets these itself;
  • the name is Authorization and Authentication is not None. Use the API key or OAuth fields for credentials instead.

Change a server later​

Open the server from the MCP Servers list and select the edit button. You can change the display name, the server URL, the authentication, the OAuth settings and the custom headers.

Stored secrets stay as they are unless you replace or clear them:

  • API key — leave the field empty to keep the stored key. Enter a new key to replace it.
  • Client secret — leave it empty to keep the stored secret. Enter a new value to replace it, or select Clear stored client secret to remove it. Without a secret the server is treated as a public client, and the client authentication method is cleared with it.
  • Custom headers — select Replace custom headers and enter the headers you want. Saving replaces every stored header with the rows you entered. To remove them all, select Remove all stored custom headers. An open editor with no rows changes nothing.

Changing Authentication to another type replaces the credentials stored for this server. If you change it to API key, you have to enter a new key before you can save.

One warning is worth reading before you save. When the OAuth settings came from Test connection, the stored client secret belongs to the current server URL. Replacing the URL makes that secret invalid, and you have to enter it again under OAuth configuration.

Share a platform server​

A platform-owned server's page has an Access section. Turn on Share with all tenants and every user on the platform can use the server's tools. Leave it off and choose tenants under Shared with tenants, and only members of those tenants can use them. Select Save access to apply the change.

Choosing tenants needs platform tenant-management access. Without it, saving keeps the listed tenants unchanged.

A server that belongs to a tenant is not shared. Only that tenant can use it.

Who can manage a tenant's server​

A tenant's server page has an Administrators section. The users and groups listed there can edit the server's connection, update its credentials and delete it, on top of the tenant's administrators.

Select Add administrator, search by name or email, tick the users and groups you want, then select Add. Each row shows the name and whether it is a User or a Group, and has a remove button. See Access to one resource for the full steps.

There is no use-only list for an MCP server. Every member of the tenant can already use its tools.

Troubleshooting​

OAuth reports missing parameters in Safari​

Safari's advanced tracking and fingerprinting protection can interfere with some OAuth authorization pages. For example, HubSpot may report that client_id and redirect_uri are missing even though they are present in the URL.

Open Safari > Settings > Privacy > Advanced, turn off Use advanced tracking and fingerprinting protection and start the OAuth connection again. You can turn the setting back on after completing the authorization.