Skip to main content

Connecting MCP Servers

A tenant defines each MCP server once, agents mount it by name, and every user connects their own account from the chat. Hosted servers (HubSpot, GitHub, Google, Slack, Atlassian, Microsoft 365) all use the Streamable HTTP transport with OAuth sign-in; see MCP Tools for the agent-side schema.

Every provider guide follows the same steps:

  1. Set up the provider: usually register an OAuth app. Providers that support Dynamic Client Registration (DCR) need no app.
  2. Add the server to the tenant in Platform Admin.
  3. Mount it on an agent.
  4. Connect from the Navigator, once per user.

Steps 2 to 4 work the same for every provider and are explained once below. The provider guides give the values.

The Platform Callback URL​

Every provider must redirect back to:

https://<your-platform-api-host>/v0/service/mcp/oauth/callback

For Zeta Alpha SaaS that is https://api.zeta-alpha.com/v0/service/mcp/oauth/callback. On-prem installations use the API host configured for the tenant.

Trailing slashes matter

Google and Slack treat …/callback and …/callback/ as different URIs. Whatever you register on the provider must match the server's Redirect URI byte-for-byte.

Adding a Server to the Tenant​

In Platform Admin, open the tenant, go to MCP Servers and click Edit. Add MCP server opens a form:

GroupFieldValue
ServerNameHow agents, access rules and users' connections refer to the server, e.g. github.
DescriptionWhat the server is for. The agent reads it to decide when to connect the server.
TransportStreamable HTTP for hosted servers.
URLThe provider's MCP endpoint.
Sign-inOAuth resource URLThe MCP server the token is for. Empty while other sign-in fields are set: the server's URL.
Authorization server URLLeave empty to use the one the server advertises. Set it to sign users in elsewhere, e.g. your Entra tenant.
OAuth client IDThe app registered on the provider. Leave empty for DCR.
ScopesSpace-separated scopes, requested when the server does not advertise its own.
Redirect URIEmpty: the platform callback URL. Set it only when the provider registered a different spelling, e.g. with a trailing slash.
OAuth client secretPick a stored tenant secret, or New secret… to store a new one.
Authorization headerOnly for servers that take a static token instead of OAuth.
HeadersExtra request headers sent on every call to the server, each a name and a value.
Shown to usersApp name, Icon URLName and icon in the chat's Connected apps list and on the approval card of the server's tools.
Who can use itEveryone, Only these, Everyone except or Nobody, saved in the tenant's access rules. See Control who can use what.

The platform derives the rest of the OAuth client: a client with a secret sends it in the token request body (client_secret_post), a client without one sends none. For reference, the form stores a server like this in the tenant's mcp_configurations (visible under Edit Tenant JSON):

{
  "name": "github",
  "description": "Repositories, issues and pull requests on GitHub.",
  "transport": "streamable-http",
  "transport_config": {
    "streamable_http": {
      "url": "https://api.githubcopilot.com/mcp/",
      "oauth_client": {
        "server_url": "https://api.githubcopilot.com/mcp/",
        "client_id": "<client ID>",
        "client_metadata": {
          "redirect_uris": [
            "https://api.zeta-alpha.com/v0/service/mcp/oauth/callback"
          ]
        }
      }
    }
  },
  "client_secret_ref": "github-client-secret",
  "display": { "app": "GitHub", "icon_url": "<icon URL>" }
}

Settings the form does not show go in that JSON; values set there win over what the platform derives. The tenant stores credentials as secrets: client_secret_ref and headers_refs name them, and the platform fills them in when it connects. Never put a secret value in transport_config.

Mounting a Server on an Agent​

Open the agent in Platform Admin (Tenant → Agent & LLM Overview → [your agent], see Managing Agents in the Platform), edit it, enable the MCP Tools capability and pick the server under Mount a server…. New MCP server… adds a server to the tenant and mounts it in one step.

In the agent's JSON, a mount is the server's name:

{
  "mcp_tools_provider_configuration": {
    "enabled": true,
    "mounts": [
      { "name": "github" },
      { "name": "hubspot", "include_tools": ["<tool name>"] }
    ]
  }
}

include_tools and exclude_tools on a mount take the server's own tool names. Several agents can mount the same server.

Connecting from the Navigator​

Tokens are stored per user: every user signs in to each server with their own account, from Connected apps in the chat or through the Authorize button the agent shows when a request needs the server. The steps and each user's controls are in Connected apps.

When a server's URL or sign-in settings (OAuth resource URL, authorization server URL, client ID or scope) change, every user shows Not connected and signs in again.

Guides​