Skip to content

MCP Endpoint

Backend.AI GO can act as an MCP (Model Context Protocol) server: external MCP clients such as Claude Code, Claude Desktop, Codex CLI, and IDE integrations connect to a single HTTP endpoint and call Backend.AI GO's built-in tools (file search, shell and Python execution, web fetch, Data Hub access, and more).

This is the opposite direction from Settings > Tools & extensions > MCP Servers, which connects Backend.AI GO to remote MCP servers as a client. The MCP endpoint makes Backend.AI GO itself the server. It speaks the MCP Streamable HTTP transport, protocol revision 2025-03-26, at:

POST http://127.0.0.1:8001/api/v1/mcp

The port is the Management API server port (default 8001). The MCP Endpoint card always shows the address the server is listening on right now, so copy the URL from there rather than typing it.

Enabling the endpoint

The endpoint is off by default. While disabled, /api/v1/mcp answers 404 Not Found, so a stock installation exposes nothing.

  1. Open API > Management API and turn on Enable MCP endpoint. This also turns on the Management API server that serves the endpoint, if it was off.
  2. Copy the connection URL shown in the card. The card shows a URL only while the server is actually listening; if the server is off or failed to start (for example, the port is already in use), the card says so instead, and the Management API server card directly above it is where you fix it.
  3. To change the port, require an API key, or allow access from other devices, use the Management API server card on the same tab.

The Management API server and the MCP endpoint are two separate switches. Turning the MCP endpoint on also turns the server on, because the endpoint cannot work without it. Turning the MCP endpoint off leaves the server running for other clients, and turning the server off under API > Management API leaves the MCP toggle on but shows the endpoint as unreachable until the server is back.

Connecting Claude Code

With Require API key on (API > Management API), requests must carry an access key issued under API > Access keys, sent as the X-API-Key header:

claude mcp add --transport http backend-ai-go http://127.0.0.1:8001/api/v1/mcp \
  --header "X-API-Key: <your-access-key>"

With Require API key off (the default on a localhost bind), omit the --header flag. The card's Claude Code command already reflects the current setting.

Then verify inside a Claude Code session:

/mcp

The backend-ai-go server should be listed as connected, with the tool catalog available. Any other MCP client that supports the Streamable HTTP transport works the same way: give it the URL and the X-API-Key header.

Which tools are exposed

The endpoint advertises the same built-in tool catalog the app's own agent uses, filtered to what can actually run over this transport:

  • Tools that require the desktop app shell (clipboard, notifications, audio transcription, image generation, memory bank, and the AppControl tools such as load_model or list_downloads) are not advertised, because they need a running desktop UI process state that the HTTP transport does not carry.
  • Tools denied by an enterprise tool allow/deny policy are not advertised, and a call to one is rejected. Policy enforcement and audit logging go through the same shared execution service as the REST POST /api/v1/tools/execute path, so MCP-initiated calls are gated and audited identically.

A failed tool call (including a policy rejection) is reported as an MCP tool result with isError: true, as the MCP specification requires; JSON-RPC errors are reserved for protocol faults such as an unknown method.

Protocol details

  • Supported methods: initialize, notifications/initialized, tools/list, tools/call, and ping.
  • initialize assigns an Mcp-Session-Id header that clients must send on every later request. Sessions expire after an idle timeout (default 1 hour) and are capped in number (default 10). At the cap a new initialize evicts the least recently used session rather than failing, so a client that restarts without sending DELETE never locks itself out. An expired, evicted, or unknown session id answers 404, telling the client to re-initialize.
  • DELETE /api/v1/mcp with the session id header terminates a session explicitly.
  • GET /api/v1/mcp answers 405 Method Not Allowed: this server responds with plain JSON per request and does not offer the optional server-to-client SSE stream.
  • JSON-RPC batch requests (a top-level array) are rejected with a single JSON-RPC error.
  • The resources, prompts, and sampling capabilities are not offered; the endpoint advertises tools only.

Security notes

  • Anyone who can reach the endpoint can run tools, including shell and Python execution. Keep access keys secret and treat them like a shell credential.
  • Default binding is localhost. The Management API binds 127.0.0.1 by default, so only processes on the same machine can reach the endpoint. With the default Require API key off, every local process can call it; turn the key requirement on under API > Management API if that is not acceptable on your machine.
  • No unauthenticated network exposure. The desktop app refuses to start the Management API on a non-localhost address (such as 0.0.0.0) unless Require API key is on. The Allow access from other devices switch stays disabled until the key requirement is enabled, and a hand-edited settings.json that combines the two is reported as a start failure rather than served.
  • Requests carrying a browser Origin header from a non-localhost origin are rejected, which blunts DNS-rebinding attacks against the localhost binding.
  • Loopback host guard. While the Management API is bound to a loopback address, it rejects any request whose Host header is not a loopback host, and any request carrying a non-loopback Origin that is not listed in the configured CORS allowed origins. This is what stops a web page from reaching the local server after rebinding its own domain to 127.0.0.1. The guard covers every route, not just the MCP endpoint, and is off when the server is bound to a non-loopback address, where authentication is required instead.
  • A POST must carry Content-Type: application/json, the media type the Streamable HTTP spec has clients send. Any other type is refused with 415 Unsupported Media Type. This is what stops a web page served from some other port on the same machine from driving a tool call: the content types a browser may send cross-origin without a preflight are exactly the ones the endpoint refuses.
  • Turning the toggle off immediately hides the endpoint again (404), with no restart needed.