How MCP works on the platform
The MCP Gateway, Managed and Remote servers, credential modes, and the tool allowlist.
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
| Term | Meaning |
|---|---|
| Connector | An addressable MCP server an authorized user has registered to an organization. The Portal lists them under Connectors. |
| Managed Server | A Connector whose container the platform runs inside the cluster. |
| Remote Server | A Connector that runs outside the platform. The platform stores only its address. |
| Upstream | The third-party system the Connector acts against, such as GitHub, Linear, or Notion. |
| MCP Gateway | The single authenticated entry point that every MCP call passes through. |
| Credential mode | Whose identity a Connector reaches its Upstream as. Chosen when the server is added. |
| User Credential | The secret that authorizes one user against one Connector's Upstream. An unauthenticated server has none. |
| Linking | The act of a user supplying their User Credential for a Connector. |
| Tool Allowlist | The 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.
- Validates the caller's platform token or API key.
- Confirms the server belongs to the caller's organization and that the caller holds
mcp.server.use. - Removes the caller's platform credential from the request.
- 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
Authorizationheader at all. - 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 Server | Remote Server | |
|---|---|---|
| Where it runs | Inside the platform cluster | Outside the platform |
| What you supply | Container image, port, path, arguments, environment | An https:// or http:// address |
| Who keeps it running | The platform | Whoever operates it |
| Status reporting | Live status from the cluster | None. The platform polls nothing |
| Environment variables | Supported, write-only | Not applicable |
| Private image registry | A pull credential, write-only | Not applicable |
| Tool allowlist | Applies | Applies |
| Credentials | Whichever credential mode the server declares | Whichever 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 mode | Upstream identity | Linking |
|---|---|---|
Each user links their own (per_user) | The calling user's own User Credential | Every member links for themselves before they can use the server |
Unauthenticated (anonymous) | None. The Gateway sends no Authorization header | Not applicable. The server takes no User Credential from anyone |
per_user is the default. It applies to Managed and Remote servers alike.
Each user links their own
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.