# How MCP works on the platform (/docs/ai/mcp/how-it-works)



Model Context Protocol support on BullSequana AI rests on four ideas. An MCP Server belongs to an organization. A Platform Admin decides which servers exist and which of their tools may be called. Each user supplies their own credential for the system behind the server. Every call travels through one authenticated entry point, the MCP Gateway.

## Vocabulary [#vocabulary]

| Term            | Meaning                                                                                |
| --------------- | -------------------------------------------------------------------------------------- |
| MCP Server      | An addressable MCP endpoint a Platform Admin has made available to an organization.    |
| Managed Server  | An MCP Server whose container the platform runs inside the cluster.                    |
| Remote Server   | An MCP Server that runs outside the platform. The platform stores only its address.    |
| Upstream        | The third-party system the MCP Server acts against, such as GitHub, Linear, or Notion. |
| MCP Gateway     | The single authenticated entry point that every MCP call passes through.               |
| User Credential | The secret that authorizes one user against one MCP Server's Upstream.                 |
| Linking         | The act of a user supplying their User Credential for an MCP Server.                   |
| Tool Allowlist  | The subset of a server's tools a Platform Admin permits the organization to call.      |

## The MCP Gateway [#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 MCP Server. There is no merged endpoint that fans out across several servers.

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 may use it.
3. Removes the caller's platform credential from the request.
4. Puts the caller's linked User Credential in its place.
5. Applies the Tool Allowlist, then forwards the request to the MCP Server.

<Mermaid
  chart="flowchart TD
    A[MCP client or Agent] --> B[MCP Gateway]
    B --> C[Validate the platform token or API key]
    C --> D[Check organization ownership and permission]
    D --> E[Strip the platform credential]
    E --> F[Inject the caller's User Credential]
    F --> G[Apply the Tool Allowlist]
    G --> H[Managed Server in the cluster]
    G --> I[Remote Server outside the platform]
    H --> J[Upstream system]
    I --> J"
/>

The platform credential never reaches an MCP Server 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 [#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                     |
| Tool allowlist        | Applies                                             | Applies                            |
| Credentials           | Each user links their own                           | Each user links their own          |

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 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 [#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.

## Every user links their own credential [#every-user-links-their-own-credential]

An MCP Server 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 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.

Every server requires a link, including one whose Upstream needs no account. There is no unauthenticated mode.

Sharing an Agent shares its definition, not access. A member running an Agent someone else built reaches only the MCP Servers 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](/docs/ai/mcp/link-your-credential).

## The tool allowlist [#the-tool-allowlist]

A Platform Admin 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 MCP Server.

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

See [Restrict which tools an MCP Server offers](/docs/ai/mcp/tool-allowlist).

## Ownership and roles [#ownership-and-roles]

An MCP Server belongs to exactly one organization. Only an administrator of that organization can create, edit, or delete one. Every member can list the servers and use them.

MCP Servers 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 the administrator sets.

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.

## Related pages [#related-pages]

* [Add an MCP Server](/docs/ai/mcp/add-a-server)
* [Link your credential to an MCP Server](/docs/ai/mcp/link-your-credential)
* [Connect an MCP client to the Gateway](/docs/ai/mcp/connect-a-client)
* [MCP reference](/docs/ai/mcp/reference)