Skip to main content
Version: 3.4.0-rc.2

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.

The platform supports MCP revision 2026-07-28 and compatible servers using the earlier initialization handshake. Test connection tries the newer discovery method first, then falls back to the older handshake when the response indicates that the newer method or protocol version is unsupported. You do not need to select a protocol version manually.

Private-network MCP servers​

A private-network MCP requires a platform-admin-managed MCP network policy (MCPNetworkPolicy) covering its destination IP addresses. Policies contain private IP addresses or CIDRs. Multiple policies contribute a combined set of permitted networks; an MCP does not need to be assigned to a policy.

An existing MCP registration does not bypass these checks; private destinations still require a matching policy in the platform's local policy view. Creating a registration or changing its URL validates the destination against the policy view available at that time. Administrators can still edit metadata without changing the URL when a policy is missing. Policy changes take effect as described under Policy changes below.

Root admins manage these policies under Manage platform → MCP Servers → Add Private Networks. Permission to manage MCP registrations does not grant permission to manage network policies. The Add Private Networks button and Platform-level Approved Private Networks list are visible only to users with network-policy management permission. If these controls are missing, ask a root admin which networks are approved or to add the approval you need.

For example, permitting 10.20.30.0/24 allows MCP destinations within that network. Prefer an individual IP address when only one destination needs access. Individual IPv4 and IPv6 addresses are stored as /32 and /128 CIDRs.

Networks must be entirely within 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, or fc00::/7. CIDRs must use their network address: use 10.20.30.0/24, not 10.20.30.42/24. Protected destinations, including loopback, link-local, and protected metadata addresses, remain blocked.

An MCP network policy permits the platform to contact a private destination. It does not create firewall rules or Kubernetes NetworkPolicies, establish routing, grant users permission to use an MCP, or disable TLS certificate verification. Network connectivity and trusted TLS certificates must be configured separately.

Public MCP destinations allowed by the platform's public-address policy require no private-network policy. HTTPS and existing authentication and authorization requirements still apply.

Every destination IP address, including all addresses obtained through DNS resolution, must be permitted. If any private destination address is not covered by a policy, the platform rejects the request.

Add an approval​

Select Add Private Networks to open the form, then enter:

  • Permitted Networks — one private IP address or CIDR per line.
  • Description — optional context explaining why the networks are approved.

Select Add Approval to save and return to the MCP Servers page. The new approval appears under Platform-level Approved Private Networks, below the MCP connections. An authorized MCP manager can then use the existing MCP registration flow for a destination covered by the approved networks.

Approvals cannot be edited in the portal. To change the permitted networks or description, add a new approval with the desired values, then remove the old one. Removing an approval removes every network it lists from that policy. Keep networks you may want to remove independently in separate approvals.

Policy changes​

Policy changes may take a short time to apply. Removing a policy can block connections to affected MCPs, unless another policy permits the same destination. It does not delete MCP registrations or stop requests already in progress.

If policy updates are interrupted, previously allowed connections may remain permitted until updates resume. Do not rely on policy deletion for an immediate network-access cutoff.

Remove an approval​

Under Platform-level Approved Private Networks on the MCP Servers page, select the row's trash icon, review the permitted networks and description, then confirm with Remove Approval.

Removal is subject to the asynchronous propagation described above. Removing an approval does not delete MCP registrations or their access grants.

If the approval changed or disappeared while the confirmation was open, removal is refused. Return to the list and review the current approval before confirming again; the portal does not silently delete a newer version.

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. Leave the authorization and token URLs blank to let the platform discover them from the server's metadata, or fill them in yourself. Add the OAuth callback URL shown in the form to the allowed callback URLs of the OAuth application. For the full flow, discovery rules, and troubleshooting, see OAuth for external MCP servers.

The platform never shows a stored API key again. When a key is stored, the server's page shows API key with the value Configured. When no key is stored yet, the API key line is not shown at all.

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. The page has two tabs. General shows the server itself, in one Configuration card. Users holds the access sections. The chosen tab is part of the page address, so you can bookmark it or send the link to someone else. Delete stays at the top right of the page.

Select Edit on the Configuration card. The fields open in place, and you can change the display name, the server URL, the authentication, the OAuth settings and the custom headers. Save or cancel before you leave: switching to the Users tab closes the editor and drops the changes you have not saved.

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

  • API key — the form shows Configured when a key is stored. Select Replace API key and enter a new key to replace it. Change nothing and the stored key stays as it is. When no key is stored, the button reads Add API key.
  • 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 on the Users tab. 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 administrators and the users or groups listed under Administrators can edit or delete its servers and update their credentials.

On the server page, select the Users tab and find Administrators. Select Add administrator, search by name or email, select the users and groups, then select Add. See Access to one resource for details.

There is no use-only list. Every tenant member can use the server's 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.

For other OAuth connection failures — issuer mismatch, discovery, scope conflicts — see OAuth troubleshooting.