Connect an MCP client to the Gateway

Point a coding agent or a desktop MCP client at a Connector's Gateway URL.

Agentic Friendly

Any MCP client that speaks Streamable HTTP can call a Connector through the MCP Gateway. Coding agents, desktop assistants, and scripts all use the same address and the same authentication.

The Gateway publishes one URL per Connector. There is no merged endpoint, so a client that needs three servers gets three entries.

Before you start

Link your credential to the server first. Until you do, the Gateway refuses every call to it. See Link your credential to a Connector.

A server whose credential mode is Unauthenticated needs no link. Its Portal page says so in place of the credential card, and the Gateway never refuses your calls to it for a missing credential.

Create a BSQAI API key under API Keys in the Portal's account menu, at the bottom of the sidebar. A key is more practical than a JWT for a tool configuration that has to keep working. The full secret is shown once and looks like sk-bsq-v1-....

Give the key mcp.server.use, which the Gateway requires on every call. Add mcp.server.list or mcp.server.read only if the key also reads gateway_url from the BSQAI API: the server list returns it for every server, and a single server's response returns it for that server. A key cannot carry mcp.credential.link, so link your credential while signed in to the Portal. See Create and use an API key.

Get the Gateway URL

Open the server in the Portal and find the MCP Gateway URL card. Select Copy.

The URL has this shape:

https://mcp-gateway.<platform-domain>/servers/<server-id>/mcp

The same value is on gateway_url in the API response for the server. It is empty when the deployment has not published a Gateway address, and the Portal says so rather than showing a URL that resolves nowhere. The platform operator sets that address as part of the deployment.

The Gateway address is not the same as the BSQAI API address. The Gateway runs as its own service so that long-lived MCP sessions do not compete with chat traffic.

Configure a client

Most MCP clients read a JSON block of this shape. The Portal generates it for you with the URL already filled in.

{
  "mcpServers": {
    "bsqai-mcp-server": {
      "type": "http",
      "url": "https://mcp-gateway.<platform-domain>/servers/<server-id>/mcp",
      "headers": {
        "Authorization": "Bearer sk-bsq-v1-..."
      }
    }
  }
}

Three things matter, whichever client you use.

  • The transport is Streamable HTTP, written "type": "http" in most clients. The Gateway does not serve stdio or the deprecated SSE transport.
  • The API key goes in the Authorization header as a bearer token.
  • Each Connector needs its own entry, under its own name.

Where that block lives differs per client. Claude Desktop and Cursor read it from their own settings file. Coding agents that support MCP read an equivalent file in the project or the user configuration directory. Check the client's own documentation for the path.

For connecting a coding agent to platform models rather than to tools, see Developer Tools.

Check the connection

export GATEWAY_URL="https://mcp-gateway.<platform-domain>/servers/<server-id>/mcp"
export BSQAI_TOKEN=sk-bsq-v1-...

curl -X POST "$GATEWAY_URL" \
  -H "Authorization: Bearer $BSQAI_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

The Accept header is required. Streamable HTTP refuses a request that does not accept both content types, so the command fails without it.

A successful reply lists the tools the server offers, already filtered by the tool allowlist. A tool an administrator has not permitted does not appear, and cannot be called by name.

What the Gateway does with your request

Your API key authenticates you to the platform and nothing more. The Gateway removes it from the request before forwarding. What it puts in its place depends on the server's credential mode: your linked User Credential, or nothing at all on an unauthenticated server. Your platform credential never reaches the Connector or the system behind it either way.

The Gateway also confirms on every call that the server belongs to your organization and that you may still use it, whatever the credential mode. A permission removed while a session is open takes effect on the next call.

When something fails

The Gateway answers in JSON-RPC rather than the platform's usual error envelope, because MCP clients parse nothing else. Most clients surface the message field.

MessageCauseWhat to do
Unknown tool: <name>The tool is outside the allowlist, or the server does not offer itAsk a user with mcp.server.update to permit it
No credential is linkedYou have not linked this server, and it expects a credentialLink it in the Portal
The credential was refusedThe upstream system rejected your credential. On an unauthenticated server, it wants authentication the server does not sendLink it again, or ask a tenant administrator to check the server's credential mode
The credential has expiredAn OAuth link the platform could no longer renewLink it again with OAuth
Access denied to MCP ServerThe server does not exist, belongs to another organization, or you may not use itCheck the URL and your organization
The MCP Server could not be reachedThe workload or remote endpoint did not answerCheck the server's status in the Portal

The three credential refusals answer 403 with a bearer challenge whose error names the problem: mcp_credential_not_linked, mcp_credential_rejected, or mcp_credential_expired. They are deliberately not invalid_token, because your platform key is fine and refreshing it would not help. A 401 with error="invalid_token" means the Gateway refused the platform key or token itself: check that it is current and sent as a bearer token.

On this page