MCP reference

Endpoints, server fields, status values, and error codes for Connectors (MCP servers) and the MCP Gateway.

Agentic Friendly

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

MethodPathRequired permissionResult
POST/v1/mcp/serversmcp.server.create200 with the server
GET/v1/mcp/serversmcp.server.list200 with servers and count
GET/v1/mcp/servers/{server_id}mcp.server.read200 with the server
PUT/v1/mcp/servers/{server_id}mcp.server.update200 with the server
DELETE/v1/mcp/servers/{server_id}mcp.server.delete204
GET/v1/mcp/servers/{server_id}/available-toolsmcp.server.use200 with tools and count
PUT/v1/mcp/servers/{server_id}/credentialmcp.credential.link204
DELETE/v1/mcp/servers/{server_id}/credentialmcp.credential.unlink204
POST/v1/mcp/servers/{server_id}/credential/oauthmcp.credential.link200 with authorize_url and state
POST/v1/mcp/credential/oauth/callbackmcp.credential.link200 with server_id
GET/v1/mcp/oauth/redirect-urimcp.server.read200 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

MethodPath
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

FieldTypeRules
runtime"managed" or "remote"Chooses the request shape. Cannot change after creation
namestringLowercase DNS label, 1 to 63 characters, unique in the organization. Create only
display_namestring1 to 200 characters
descriptionstring or nullUp to 500 characters. Defaults to null
tool_allowlistarray of stringsDefaults to [], which permits every tool
credential_mode"per_user" or "anonymous"Defaults to "per_user". Create only
oauth_clientobject or nullThe 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.

ValueUpstream AuthorizationLinking
per_userBearer with the calling user's own User CredentialRequired per user. An unlinked caller is refused with mcp_credential_not_linked
anonymousNo header at allRefused 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.

FieldTypeRules
client_idstringRequired. 1 to 255 visible ASCII characters, no spaces
client_secretstring or nullUp to 1024 characters. Write-only
scopesarray of stringsUp to 100 entries of 1 to 255 visible ASCII characters. [] requests the provider's default
authorization_serverstringRequired. 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 updateEffect
No oauth_client fieldRemove the app registration
oauth_client without client_secret, or with "client_secret": nullKeep 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

FieldTypeRules
imagestringRequired. Registry-qualified with a tag or digest. Up to 512 characters
portintegerRequired. 1 to 65535
pathstringDefaults to /mcp. Must start with /
argumentsarray of stringsDefaults to []. Replaces the image's default command
envobject of stringsNames match ^[A-Za-z_][A-Za-z0-9_]*$. Write-only
resourcesobjectcpu_request, memory_request, cpu_limit, memory_limit. Each a string or null
securityobjectrun_as_non_root, run_as_user, run_as_group, read_only_root_filesystem. Each nullable
image_pull_credentialobject or nullusername, 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 sendEffect
No env fieldKeep the stored environment
"env": nullKeep 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 updateEffect
No image_pull_credential fieldKeep the stored credential
"image_pull_credential": nullRemove the stored credential
username and passwordReplace 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

FieldTypeRules
addressstringRequired. 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 fieldMeaning
envNames only, each with configured: true. Values are never returned
namespaceWhere the platform runs a Managed Server. null for a Remote Server
image_pull_credentialregistry and username of the stored pull credential, or null. The password is never returned
credential_modeWhose identity reaches the Upstream: per_user or anonymous
oauth_clientThe app registration without its secret, or null
linkedWhether the calling user has linked a credential. Yours alone. Always false on an anonymous server
credential_last_used_atWhen your credential was last used, or null. Always null on an anonymous server
statusLive workload status, or null
gateway_urlThe 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 sendEffect
No mcp_server_ids fieldKeep the current list
nullKeep the current list
[]Remove every server
A list of identifiersReplace 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.

StatusCodeMeaning
400mcp_server_address_invalidThe Remote address broke a rule the message names
400mcp_server_image_invalidThe image reference is not one the cluster would accept
400mcp_server_runtime_mismatchThe update used the other runtime's shape
400mcp_server_does_not_use_oauthThe server presented no OAuth challenge
400mcp_server_needs_no_credentialThe server is anonymous, so it takes no User Credential from anyone
400mcp_server_image_pull_credential_invalidThe image pull credential cannot be used. The message names why, for example a stored credential for another registry than the new image
400mcp_oauth_state_invalidThe state is unknown, expired, already used, or another user's
400mcp_server_oauth_client_invalidThe oauth_client cannot be used. The message names the problem
400mcp_oauth_client_rejectedThe provider refused the Connector's app registration
400mcp_oauth_access_deniedSign-in was canceled or refused at the provider
400agent_mcp_server_not_in_organizationAn Agent referenced a server outside the organization
403mcp_server_access_deniedThe server is absent, another organization's, or not yours to use
403mcp_server_management_deniedThe caller lacks the required MCP server-management permission
403mcp_credential_not_linkedNo credential is linked for this per_user server
403mcp_credential_rejectedThe upstream system refused the linked credential
403mcp_credential_expiredAn OAuth credential that can no longer be renewed
409mcp_server_name_conflictAnother server in the organization has that name
409mcp_server_tenant_not_readyThe organization's tenant runtime is not ready for Managed Servers yet, or the tenant is being deleted. Nothing was recorded
500mcp_server_oauth_client_unreadableThe stored client secret of the app registration cannot be read. An administrator enters it again
500mcp_credential_unreadableA stored User Credential can no longer be decrypted. The user links it again
500mcp_server_internal_errorAn unexpected failure in a Connector operation
503mcp_server_environment_not_storedThe environment could not be written, so nothing was recorded
503mcp_server_image_pull_credential_not_storedThe image pull credential could not be written to the cluster. Nothing was changed; try again
503mcp_server_not_readyThe Managed workload is not serving yet
503mcp_server_unreachableThe server did not answer or did not complete an MCP handshake
503mcp_oauth_upstream_errorOAuth discovery, registration, or exchange failed. Retrying is the remedy
503mcp_oauth_not_configuredThe 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 codePlatform code
-32001None. The platform token or API key is missing or invalid. HTTP 401 with the challenge Bearer realm="mcp-gateway", error="invalid_token"
-32002mcp_server_access_denied
-32003mcp_credential_not_linked
-32004mcp_credential_rejected
-32005mcp_credential_expired
-32600mcp_oauth_client_rejected
-32603mcp_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.

On this page