MCP reference

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

There is no PATCH. Updates use PUT and replace what they send.

DELETE /v1/mcp/servers/{server_id} is idempotent. An administrator gets 204 whether or not the server existed.

Gateway endpoint

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

Unknown fields, and fields belonging to the other runtime, are rejected with 422.

Sending name on an update is rejected. To rename what people read, change display_name.

Managed Server fields

A null field in resources or security leaves the platform's default alone.

A Managed Server runs one replica.

Environment semantics on update

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.

Remote Server fields

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 },
  "tool_allowlist": ["search_issues"],
  "created_at": "2026-08-28T09:14:22Z",
  "updated_at": "2026-08-28T09:14:22Z",
  "credential_mode": "per_user",
  "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"
}

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

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": "..." }

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 MCP Servers an Agent may reach. On POST /v1/agents, omit the field or send [] to create an Agent without MCP Servers. On PUT /v1/agents/{config_id}, the update semantics are:

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 has linked and may use. The rest contribute no tools.

Error codes

Management endpoints answer with the platform error envelope. Request validation failures answer 422 without an error code.

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" }
  }
}

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.

The three credential refusals also carry a WWW-Authenticate bearer challenge whose error parameter matches the code in the body.

Related pages

• How MCP works on the platform
• Add an MCP Server
• Connect an MCP client to the Gateway