How MCP works on the platform

The MCP Gateway, Managed and Remote servers, credential modes, and the tool allowlist.

Agentic Friendly

Model Context Protocol support on BullSequana AI rests on four ideas. A Connector belongs to an organization. Tenant administrators and delegated MCP managers control server registrations and allowed tools. Each user supplies their own credential for the system behind the server, unless that system needs no account. Every call travels through one authenticated entry point, the MCP Gateway.

Vocabulary

TermMeaning
ConnectorAn addressable MCP server an authorized user has registered to an organization. The Portal lists them under Connectors.
Managed ServerA Connector whose container the platform runs inside the cluster.
Remote ServerA Connector that runs outside the platform. The platform stores only its address.
UpstreamThe third-party system the Connector acts against, such as GitHub, Linear, or Notion.
MCP GatewayThe single authenticated entry point that every MCP call passes through.
Credential modeWhose identity a Connector reaches its Upstream as. Chosen when the server is added.
User CredentialThe secret that authorizes one user against one Connector's Upstream. An unauthenticated server has none.
LinkingThe act of a user supplying their User Credential for a Connector.
Tool AllowlistThe subset of a server's tools the server configuration permits the organization to call.

The MCP Gateway

The Gateway is a separate service from the BSQAI API, with its own address and its own workload. It publishes one URL per Connector. There is no merged endpoint that fans out across several servers.

Two kinds of caller reach the Gateway. An external MCP client, such as a coding agent, calls a server's Gateway URL itself. Portal chat, Build chats, Agents, and Responses API requests that run an Agent are executed by the BSQAI API, which calls the Gateway on the member's behalf. Both take the same path.

On every request the Gateway does five things.

  1. Validates the caller's platform token or API key.
  2. Confirms the server belongs to the caller's organization and that the caller holds mcp.server.use.
  3. Removes the caller's platform credential from the request.
  4. Applies the server's credential mode: it puts the caller's linked User Credential in place of what it removed, renewing an OAuth link whose access has expired, or sends no Authorization header at all.
  5. Applies the Tool Allowlist, then forwards the request to the Connector.

The Gateway logs every tool call with the user, the server, and the tool name before it applies the allowlist, so a refused attempt is recorded too. On the way back, it removes the tools outside the allowlist from the tool listings in the reply.

The platform credential never reaches a Connector or an Upstream. The Gateway removes it and replaces it in separate steps, so no ordering leaves the caller's token in the forwarded request.

The Gateway reads the address of a server from its stored record, so a control-plane problem in the cluster does not stop tool calls.

Managed and Remote servers

A server is one kind or the other, chosen when it is added. The choice is permanent.

Managed ServerRemote Server
Where it runsInside the platform clusterOutside the platform
What you supplyContainer image, port, path, arguments, environmentAn https:// or http:// address
Who keeps it runningThe platformWhoever operates it
Status reportingLive status from the clusterNone. The platform polls nothing
Environment variablesSupported, write-onlyNot applicable
Private image registryA pull credential, write-onlyNot applicable
Tool allowlistAppliesApplies
CredentialsWhichever credential mode the server declaresWhichever credential mode the server declares

Everything downstream of the address behaves the same for both kinds. Credential injection, the allowlist, and linking work identically.

Use a Remote Server for a hosted MCP endpoint that already exists, such as the Linear or Notion services. Use a Managed Server when you have a container image and want the platform to run it.

A tenant organization's Managed Servers run in its tenant namespace, tenant-<slug>, beside the rest of the tenant's runtime. They count against the tenant's compute quota and are removed with the tenant. Organizations without a tenant, such as the Global organization, use the shared Connector namespace, mcp-servers by default. In both, a NetworkPolicy admits only the MCP Gateway, the BSQAI API and the MCP operator to a server, on clusters whose network-policy engine enforces NetworkPolicies.

A Managed Server's outbound traffic is limited too. With the platform's network policies on, which is the default, a server reaches cluster DNS and the addresses in NETWORK_POLICY_EXTERNAL_EGRESS_CIDRS, on the ports in MCP_LIFECYCLE_OPERATOR_NETWORK_POLICY_SERVER_EGRESS_PORTS: 443 and 80 by default. The platform operator sets both. An upstream on another port needs that port added. With network policies off, or with no external addresses set, a server's egress is open. Whether 0.0.0.0/0 also matches the addresses of pods inside the cluster depends on the network-policy engine: Cilium matches only addresses outside the cluster, while Calico also matches pod addresses, so a Calico site lists its external ranges instead. A container still runs third-party code with your members' credentials, so add only images you trust.

A Remote Server address must be publicly resolvable. Addresses inside the cluster are refused, including private IP ranges, localhost, and hostnames ending in svc.cluster.local. An MCP server running inside this cluster is a Managed Server.

Managed Server requirements

A Managed Server runs one replica. The count is not configurable, because the operator pins MCP sessions by source address and every user shares the Gateway's address.

The image must already serve MCP over Streamable HTTP. The platform does not adapt a stdio server. Most images start in stdio mode and need a switch to serve HTTP, and the switch differs per image. Some read it from the environment, others take it as a command argument.

Containers run as a non-root user with a read-only root filesystem and all capabilities dropped. An image that cannot run under those defaults needs an explicit security exception on the server record.

An image from a private registry needs a pull credential on the server record: a username and a password or access token for the registry in the image reference. The platform uses it only to pull the image. The container never sees it.

Credential modes

Every Connector declares a credential mode when it is added. The mode decides whose identity, if any, reaches the upstream system. It is part of how the server is registered and cannot be changed afterwards.

Credential modeUpstream identityLinking
Each user links their own (per_user)The calling user's own User CredentialEvery member links for themselves before they can use the server
Unauthenticated (anonymous)None. The Gateway sends no Authorization headerNot applicable. The server takes no User Credential from anyone

per_user is the default. It applies to Managed and Remote servers alike.

A Connector in this mode reaches its Upstream as the individual calling user, never as one shared organization identity. A shared identity would let every member read everything that identity can read, past the Upstream's own access controls, with no record of who asked.

Three consequences follow.

A user who has not linked such a server cannot see or call its tools. The tools are absent rather than refused, so a model never proposes a call that cannot succeed.

A call that arrives without a link is refused with mcp_credential_not_linked. There is no shared identity to fall back on.

Sharing an Agent shares its definition, not access. A member running an Agent someone else built reaches only the Connectors they linked themselves. The Agent editor names the servers the viewer still has to link.

User Credentials are encrypted before they are stored, are never returned by any endpoint, and are used only on requests made for that user. See Link your credential.

Unauthenticated

Some upstream systems need no account of their own. Context7's public documentation service is one. An unauthenticated server has no User Credential: the Gateway strips the caller's platform credential as always and forwards the request without any Authorization header. It substitutes nothing for the missing credential, neither a placeholder value nor the caller's platform token.

An unauthenticated upstream does not relax platform access control. The Gateway still validates the caller, confirms the server belongs to their organization, checks that they may use it, and applies the Tool Allowlist before it forwards anything. Unauthenticated describes the upstream system, not access to the platform.

Because there is nothing to link, linking is not a step between a member and the server's tools, in chat and in an Agent alike. Permission to use the server and the Tool Allowlist still decide what they reach. Linking a credential to it is refused rather than accepted and ignored, so a stored credential can never contradict the mode the server declares.

The mode states what the upstream system expects; it does not make that system accept the call. An upstream that wants authentication after all answers 401, which the Gateway reports as a refused credential. The remedy is to re-add the server so each user links their own credential, not to link one to the unauthenticated record.

The tool allowlist

A user with mcp.server.update chooses which of a server's tools the organization may invoke. The Gateway reads the list from the database on every request, so a change takes effect at once.

An allowlisted tool passes through. A tool outside the list is removed from tool listings and refused if a client names it directly, before the request reaches the Connector.

An empty allowlist permits every tool the server offers. There is no setting that permits none.

See Restrict which tools a Connector offers.

Ownership and roles

A Connector belongs to exactly one organization. Creating, editing and deleting one require mcp.server.create, mcp.server.update and mcp.server.delete, respectively. These are granted to tenant administrators and can be delegated through custom roles. Every member can list the servers and use them.

Connectors do not use the owner, editor, and viewer sharing model that files and agents use. A server is infrastructure. What separates one user from another is the User Credential, which is per user by construction, and the Tool Allowlist, which an authorized server manager sets. An unauthenticated server has no User Credential, so permission to use it and the Tool Allowlist are all that separate one member from another.

A caller from another organization is told the server is inaccessible. The same answer is given for a server that does not exist, so probing for identifiers reveals nothing.

On this page