Register an MCP server

Register a remote MCP server against your organisation, test that it connects, then attach it to the agents that should use its tools. Navigate to AI Services > MCP Servers in the dashboard.

You need the manage_ai_mcp_servers permission to create, edit, or delete a server. Organisation owners and administrators have it by default.

Before you start

You need:

• An MCP server reachable over HTTPS that speaks Streamable HTTP. Servers behind a private network, on localhost, or speaking stdio cannot be reached.
• Credentials for that server, if it requires them — either a bearer token or an OAuth client credentials set.

Register the server

Select Add MCP server and complete the form.

Field	Required	Description
Server name	Yes	Slug used to reference the server. Lowercase letters, digits, and hyphens; must start with a letter or digit; maximum 63 characters. Unique within your organisation.
Display name	No	Friendly name shown in the dashboard.
Server URL	Yes	HTTPS URL of the MCP endpoint, for example https://mcp.example.com/mcp.
Auth type	Yes	None, Bearer token, or OAuth client credentials.
Enabled	No	Whether agents may call the server. Defaults to enabled.
Tool allowlist	No	Which of the server’s tools to expose. Leave empty to expose all of them.

The server name becomes part of the tool identifier your agents see, so choose something recognisable — acme-crm reads better than server-2 when it appears in an audit log.

Authentication

Choose the type that matches your server.

None

For servers that require no authentication. Do not send a credentials object.

Bearer token

Supply a single token. The gateway sends it as an Authorization header to the downstream server on every call.

OAuth client credentials

Supply clientId, clientSecret, and tokenUrl, and optionally scopes. The gateway runs the client credentials flow against your server’s authorisation server and caches the resulting token, refreshing it as needed.

Note

Credentials are write-only. They are stored in Secrets Manager and are never returned by the API or shown in the dashboard after saving. The server record carries hasCredentials: true to indicate they are set. To replace them, enter new values; to remove them, clear the field.

Test the connection

Select Test connection. The gateway performs the full MCP handshake — initialize, version negotiation, then tools/list — against the registered server using the stored credentials.

A successful test returns:

• the protocol version negotiated with the server
• the tools the server exposes, with their descriptions
• a hash of the tool schemas, stored as the schema pin

Run the test before attaching the server to an agent. It is the fastest way to catch a wrong URL, an expired token, or a server that is not reachable from outside your network.

If the test fails, the error identifies which stage failed:

Error	Meaning
ssrf-blocked	The URL resolves to a private, reserved, or link-local address.
downstream	The server was unreachable, timed out, or returned an RPC error.
governance	Your organisation’s AI configuration does not permit the call.

Restrict which tools are exposed

The tool allowlist controls which of the server’s tools your organisation can use. Leave it empty and all tools are exposed. Populate it and only the named tools are visible to agents.

Caution

An empty array means deny all. An absent or null allowlist means no restriction. This distinction is consistent across the platform and applies to both the server-level allowlist and per-agent attachments.

Narrow the allowlist when a server exposes more than your agents need. Every tool you expose adds to the prompt your agents carry and widens what a compromised server could attempt.

Attach the server to an agent

A registered server does nothing until an agent is attached to it. Edit the agent and add the server under its MCP attachments. You can narrow the tools further per agent — the effective set is the intersection of the server allowlist and the agent’s attachment list.

Attached tools are exposed to the model as mcp__{serverName}__{toolName}, so they cannot collide with built-in tools or with tools from another server.

That name is capped at 64 characters. If the combined length exceeds the cap the tool part is truncated, and characters outside a-zA-Z0-9_- are replaced with underscores. Two tools whose names differ only in those replaced characters, or only after the truncation point, collide — the first one wins and the second is skipped. Short, distinct tool names avoid the problem entirely.

Use it from QuantCode

Org-registered MCP servers sync down to QuantCode automatically through the existing configuration pipeline. They appear as remote servers pointing at the gateway, authenticated with your Quant credentials.

Your downstream credentials are never part of that sync. QuantCode talks to the gateway; the gateway talks to your server.

Payload size

MCP tool schemas and their results travel through the platform’s request payload, which is capped. A server exposing a large tool catalogue with verbose schemas can crowd out the conversation itself.

If you attach a server with many tools, use a per-agent allowlist to bring only what that agent needs.