MCP reference
Endpoints, server fields, status values, and error codes for Connectors (MCP servers) and the MCP Gateway.
Two addresses are involved. Management endpoints live on the BSQAI API under /v1/mcp. MCP traffic goes to the MCP Gateway, which is a separate service with its own address.
Authenticate with a JWT or a BSQAI API key. Both are sent as Authorization: Bearer ....
Management endpoints
| Method | Path | Required permission | Result |
|---|---|---|---|
POST | /v1/mcp/servers | mcp.server.create | 200 with the server |
GET | /v1/mcp/servers | mcp.server.list | 200 with servers and count |
GET | /v1/mcp/servers/{server_id} | mcp.server.read | 200 with the server |
PUT | /v1/mcp/servers/{server_id} | mcp.server.update | 200 with the server |
DELETE | /v1/mcp/servers/{server_id} | mcp.server.delete | 204 |
GET | /v1/mcp/servers/{server_id}/available-tools | mcp.server.use | 200 with tools and count |
PUT | /v1/mcp/servers/{server_id}/credential | mcp.credential.link | 204 |
DELETE | /v1/mcp/servers/{server_id}/credential | mcp.credential.unlink | 204 |
POST | /v1/mcp/servers/{server_id}/credential/oauth | mcp.credential.link | 200 with authorize_url and state |
POST | /v1/mcp/credential/oauth/callback | mcp.credential.link | 200 with server_id |
GET | /v1/mcp/oauth/redirect-uri | mcp.server.read | 200 with redirect_uri, or null when the deployment has none |
The MCP permission catalogue explains which roles grant these permissions and which can be delegated.
There is no PATCH. Updates use PUT and replace what they send.
DELETE /v1/mcp/servers/{server_id} is idempotent. An authorized caller gets 204 whether or not the server existed.
Gateway endpoint
| Method | Path |
|---|---|
GET, POST, DELETE | /servers/{server_id}/mcp |
POST carries messages, GET opens the server-to-client stream, and DELETE ends a session. The transport is Streamable HTTP.
The full URL is on gateway_url in every server response, and on the server's detail page in the Portal.
Fields on every server
| Field | Type | Rules |
|---|---|---|
runtime | "managed" or "remote" | Chooses the request shape. Cannot change after creation |
name | string | Lowercase DNS label, 1 to 63 characters, unique in the organization. Create only |
display_name | string | 1 to 200 characters |
description | string or null | Up to 500 characters. Defaults to null |
tool_allowlist | array of strings | Defaults to [], which permits every tool |
credential_mode | "per_user" or "anonymous" | Defaults to "per_user". Create only |
oauth_client | object or null | The app registration used for OAuth Linking. Defaults to null. See App registration |
Unknown fields, and fields belonging to the other runtime, are rejected with 422.
Sending name or credential_mode on an update is rejected. To rename what people read, change display_name. To change credential mode, delete the server and create a new one.
Credential mode
credential_mode decides what the Gateway sends to the Upstream after it strips the caller's platform credential.
| Value | Upstream Authorization | Linking |
|---|---|---|
per_user | Bearer with the calling user's own User Credential | Required per user. An unlinked caller is refused with mcp_credential_not_linked |
anonymous | No header at all | Refused with mcp_server_needs_no_credential |
anonymous changes nothing about platform authorization. The Gateway still authenticates the caller, confirms the server belongs to their organization, checks that they may use it, and applies the Tool Allowlist.
GET /v1/mcp/servers/{server_id}/available-tools follows the same rule. It opens its MCP session with the calling user's own credential on a per_user server, and with no credential on an anonymous one, so discovery needs no link there.
A response may also report credential_mode: "shared". It is reserved and cannot be set through the API.
App registration
oauth_client holds an app that an administrator registered with the provider, for upstream systems that do not support dynamic client registration, such as Microsoft Entra ID and Slack. Without one, the platform registers itself as a public client.
| Field | Type | Rules |
|---|---|---|
client_id | string | Required. 1 to 255 visible ASCII characters, no spaces |
client_secret | string or null | Up to 1024 characters. Write-only |
scopes | array of strings | Up to 100 entries of 1 to 255 visible ASCII characters. [] requests the provider's default |
authorization_server | string | Required. The provider's issuer, up to 2048 characters |
authorization_server is required, because the client secret and members' sign-ins only ever go to the authorization server the administrator named.
A response returns client_id, scopes, authorization_server, and has_client_secret. The secret itself is never returned.
| What you send on update | Effect |
|---|---|
No oauth_client field | Remove the app registration |
oauth_client without client_secret, or with "client_secret": null | Keep the stored secret. When a secret is stored and client_id or authorization_server changes, the update is refused with mcp_server_oauth_client_invalid |
"client_secret": "" | Remove the stored secret |
"client_secret": "<value>" | Replace the stored secret |
Unlike env, omitting oauth_client removes it, so a read, edit, and write cycle resends oauth_client without client_secret. Changing client_id or authorization_server, or adding or removing oauth_client, makes members who linked with OAuth link again once their current access expires. Replacing only the secret does not affect members.
oauth_client is refused with mcp_server_oauth_client_invalid on an anonymous server, and for an issuer that the platform will not call or whose metadata names another issuer. Microsoft Entra ID needs the tenant's own issuer, https://login.microsoftonline.com/<tenant-id>/v2.0. Slack's issuer is https://mcp.slack.com.
Managed Server fields
| Field | Type | Rules |
|---|---|---|
image | string | Required. Registry-qualified with a tag or digest. Up to 512 characters |
port | integer | Required. 1 to 65535 |
path | string | Defaults to /mcp. Must start with / |
arguments | array of strings | Defaults to []. Replaces the image's default command |
env | object of strings | Names match ^[A-Za-z_][A-Za-z0-9_]*$. Write-only |
resources | object | cpu_request, memory_request, cpu_limit, memory_limit. Each a string or null |
security | object | run_as_non_root, run_as_user, run_as_group, read_only_root_filesystem. Each nullable |
image_pull_credential | object or null | username, 1 to 255 characters without : or control characters, and password, 1 to 4096 characters without control characters: a password or access token for the registry in image. Write-only. See Image pull credential |
A null field in resources or security leaves the platform's default alone.
A Managed Server runs one replica.
The response's namespace is where the server runs: its organization's tenant namespace, tenant-<slug>, or the shared Connector namespace, mcp-servers by default, for an organization without a tenant. The platform sets it; a request cannot choose it.
Environment semantics on update
| What you send | Effect |
|---|---|
No env field | Keep the stored environment |
"env": null | Keep the stored environment |
"env": {"A": "1"} | Replace the whole environment with exactly those names |
"env": {} | Remove every environment variable |
Values are never returned, so a read gives you nothing to resend. Omission preserving the environment is what makes a read, edit, and write cycle safe.
Image pull credential
image_pull_credential signs the cluster in to a private registry to pull image. The registry is the host in image: ghcr.io/acme/server:1 uses ghcr.io, and an image without a registry host uses Docker Hub. The password is stored in a Kubernetes Secret that only the image pull reads. The server's container never sees it, and no endpoint returns it.
The credential is not checked when it is saved. A wrong one shows in status as an image pull error. It is used as given and never renewed, so use a long-lived token: a short-lived one, such as an Amazon ECR authorization token, stops working when it expires.
| What you send on update | Effect |
|---|---|
No image_pull_credential field | Keep the stored credential |
"image_pull_credential": null | Remove the stored credential |
username and password | Replace the stored credential |
A stored credential is kept only while image comes from the same registry. An update that changes the registry must send the credential again or remove it, or it is refused with mcp_server_image_pull_credential_invalid.
Remote Server fields
| Field | Type | Rules |
|---|---|---|
address | string | Required. Absolute http:// or https:// URL including the path, up to 2048 characters |
The address is stored exactly as sent and is never normalized. It must carry no username or password, and its host must be publicly resolvable.
A Remote Server accepts none of the Managed fields.
Server response
{
"id": "2ddb7c76-4fb1-41bc-bf04-c0ae2b4ee4f3",
"organization_id": "...",
"name": "linear",
"display_name": "Linear",
"description": null,
"runtime": "remote",
"address": "https://mcp.linear.app/mcp",
"namespace": null,
"image": null,
"port": null,
"path": null,
"arguments": [],
"env": [],
"resources": { "cpu_request": null, "memory_request": null, "cpu_limit": null, "memory_limit": null },
"security": { "run_as_non_root": null, "run_as_user": null, "run_as_group": null, "read_only_root_filesystem": null },
"image_pull_credential": null,
"tool_allowlist": ["search_issues"],
"created_at": "2026-08-28T09:14:22Z",
"updated_at": "2026-08-28T09:14:22Z",
"credential_mode": "per_user",
"oauth_client": null,
"linked": true,
"credential_last_used_at": "2026-08-28T10:02:11Z",
"status": null,
"gateway_url": "https://mcp-gateway.<platform-domain>/servers/2ddb7c76-4fb1-41bc-bf04-c0ae2b4ee4f3/mcp"
}| Response field | Meaning |
|---|---|
env | Names only, each with configured: true. Values are never returned |
namespace | Where the platform runs a Managed Server. null for a Remote Server |
image_pull_credential | registry and username of the stored pull credential, or null. The password is never returned |
credential_mode | Whose identity reaches the Upstream: per_user or anonymous |
oauth_client | The app registration without its secret, or null |
linked | Whether the calling user has linked a credential. Yours alone. Always false on an anonymous server |
credential_last_used_at | When your credential was last used, or null. Always null on an anonymous server |
status | Live workload status, or null |
gateway_url | The address an MCP client uses. null when the deployment publishes none |
Status
A Managed Server with a reported status carries this shape.
{
"ready": true,
"replicas": 1,
"ready_replicas": 1,
"url": "...",
"conditions": [
{
"type": "Ready",
"status": "True",
"reason": "...",
"message": "...",
"last_transition_time": "2026-08-28T09:15:03Z"
}
]
}ready: true means the workload is up and the platform completed an MCP handshake with it. That is stricter than the container running.
status is null for a Remote Server, always. It is also null for a Managed Server the cluster has not reported on yet. The Portal renders these as Not reported and Status unknown.
status.url is the internal workload address. It is not reachable from outside the cluster. Use gateway_url.
Credential endpoints
These endpoints serve per_user servers. On an anonymous server, PUT .../credential answers 400 with mcp_server_needs_no_credential and stores nothing. POST .../credential/oauth answers the same code, except on a deployment that publishes no OAuth return address, which is reported first as mcp_oauth_not_configured whatever the credential mode. DELETE .../credential answers 204 in every mode, so removing a credential stays idempotent.
Link or replace:
{ "credential": "<upstream token>" }The value is 1 to 4096 characters and may not be blank. The response is 204 with no body.
Start OAuth Linking with POST /v1/mcp/servers/{server_id}/credential/oauth. It takes no body and answers:
{ "authorize_url": "https://...", "state": "..." }Send the browser to authorize_url. The upstream system returns the browser to the Portal with code and state, which the Portal posts to /v1/mcp/credential/oauth/callback:
{ "state": "...", "code": "..." }When the upstream system returns an error instead of a code, the Portal posts { "state": "...", "error": "..." }. Send exactly one of code and error. A cancellation or a sign-in the member could not complete answers mcp_oauth_access_denied, and a provider outage answers mcp_oauth_upstream_error. Any other error answers mcp_oauth_client_rejected on a Connector with an app registration, and mcp_oauth_upstream_error on one without.
A state is valid once and for ten minutes. It is bound to the user and organization that started the flow, and is consumed before the code is exchanged, so a repeated post fails.
No endpoint returns a credential.
Agent integration
mcp_server_ids lists the Connectors an Agent may reach. On POST /v1/agents, omit the field or send [] to create an Agent without Connectors. On PUT /v1/agents/{config_id}, the update semantics are:
| What you send | Effect |
|---|---|
No mcp_server_ids field | Keep the current list |
null | Keep the current list |
[] | Remove every server |
| A list of identifiers | Replace the list |
Every identifier must name a server in the caller's organization. An identifier that does not returns agent_mcp_server_not_in_organization, naming every invalid entry.
At run time the agent reaches only the servers the running user may use and can reach: a per_user server the user has linked, or an anonymous server, which needs no link. The rest contribute no tools.
Portal chat and Build chats add the Connectors the member switched on for the conversation to the Agent's list. A POST /v1/responses request with agent_id runs that Agent with its mcp_server_ids. An API key used for it needs agent.configuration.use, and mcp.server.use when the Agent lists Connectors. The Responses API's mcp tool type is accepted for compatibility and ignored: a request reaches Connectors only through an Agent.
Error codes
Management endpoints answer with the platform error envelope. Request validation failures answer 422 without an error code.
| Status | Code | Meaning |
|---|---|---|
400 | mcp_server_address_invalid | The Remote address broke a rule the message names |
400 | mcp_server_image_invalid | The image reference is not one the cluster would accept |
400 | mcp_server_runtime_mismatch | The update used the other runtime's shape |
400 | mcp_server_does_not_use_oauth | The server presented no OAuth challenge |
400 | mcp_server_needs_no_credential | The server is anonymous, so it takes no User Credential from anyone |
400 | mcp_server_image_pull_credential_invalid | The image pull credential cannot be used. The message names why, for example a stored credential for another registry than the new image |
400 | mcp_oauth_state_invalid | The state is unknown, expired, already used, or another user's |
400 | mcp_server_oauth_client_invalid | The oauth_client cannot be used. The message names the problem |
400 | mcp_oauth_client_rejected | The provider refused the Connector's app registration |
400 | mcp_oauth_access_denied | Sign-in was canceled or refused at the provider |
400 | agent_mcp_server_not_in_organization | An Agent referenced a server outside the organization |
403 | mcp_server_access_denied | The server is absent, another organization's, or not yours to use |
403 | mcp_server_management_denied | The caller lacks the required MCP server-management permission |
403 | mcp_credential_not_linked | No credential is linked for this per_user server |
403 | mcp_credential_rejected | The upstream system refused the linked credential |
403 | mcp_credential_expired | An OAuth credential that can no longer be renewed |
409 | mcp_server_name_conflict | Another server in the organization has that name |
409 | mcp_server_tenant_not_ready | The organization's tenant runtime is not ready for Managed Servers yet, or the tenant is being deleted. Nothing was recorded |
500 | mcp_server_oauth_client_unreadable | The stored client secret of the app registration cannot be read. An administrator enters it again |
500 | mcp_credential_unreadable | A stored User Credential can no longer be decrypted. The user links it again |
500 | mcp_server_internal_error | An unexpected failure in a Connector operation |
503 | mcp_server_environment_not_stored | The environment could not be written, so nothing was recorded |
503 | mcp_server_image_pull_credential_not_stored | The image pull credential could not be written to the cluster. Nothing was changed; try again |
503 | mcp_server_not_ready | The Managed workload is not serving yet |
503 | mcp_server_unreachable | The server did not answer or did not complete an MCP handshake |
503 | mcp_oauth_upstream_error | OAuth discovery, registration, or exchange failed. Retrying is the remedy |
503 | mcp_oauth_not_configured | The deployment publishes no OAuth return address |
A missing server and an inaccessible one both return mcp_server_access_denied, so probing for identifiers reveals nothing.
Gateway errors
The Gateway answers in JSON-RPC 2.0. The platform code appears on error.data.code.
{
"jsonrpc": "2.0",
"id": null,
"error": {
"code": -32003,
"message": "No credential is linked for this MCP Server.",
"data": { "code": "mcp_credential_not_linked" }
}
}| JSON-RPC code | Platform code |
|---|---|
-32001 | None. The platform token or API key is missing or invalid. HTTP 401 with the challenge Bearer realm="mcp-gateway", error="invalid_token" |
-32002 | mcp_server_access_denied |
-32003 | mcp_credential_not_linked |
-32004 | mcp_credential_rejected |
-32005 | mcp_credential_expired |
-32600 | mcp_oauth_client_rejected |
-32603 | mcp_server_oauth_client_unreadable |
mcp_oauth_client_rejected and mcp_server_oauth_client_unreadable reach a Gateway caller while the platform renews a link: the provider refused the app registration, or the stored client secret cannot be read. The link is kept.
Other refusals take their JSON-RPC code from the HTTP status: 400, 409, 413, and 422 answer -32600, 404 and 405 answer -32601 for a path the Gateway does not serve, and 500 and 503, such as mcp_server_not_ready and mcp_server_unreachable, answer -32603. A missing server answers 403 with mcp_server_access_denied, never 404.
A call to a tool outside the allowlist is the one exception. It answers HTTP 200 with JSON-RPC -32602 and the message Unknown tool: <name>, carrying no data, so it is indistinguishable from a tool the server never had. On a server with a nonempty allowlist, a request body that is not valid JSON is refused the same way, with the message Request body is not valid JSON, because the Gateway cannot check what it calls.
The three credential refusals answer HTTP 403 and carry a WWW-Authenticate bearer challenge whose error parameter matches the code in the body. They are deliberately not invalid_token, because the caller's platform credential is valid and refreshing it would not help.
mcp_credential_not_linked and mcp_credential_expired never reach an anonymous server: it holds no credential to be missing or to lapse. mcp_credential_rejected still can. The Gateway raises it whenever an Upstream answers 401, and an Upstream that turns out to want authentication after all answers exactly that. It means the server's credential mode does not match what its Upstream expects, which a user with server-delete and server-create permissions resolves by re-adding the server in per_user mode.