HTTP endpoint

Connect clients that take a URL instead of a command: web agents, hosted assistants, sandboxed IDEs.

While the companion runs it serves MCP over Streamable HTTP at:

http://127.0.0.1:9223/mcp?token=<pairing token>

The token is the same one the extension pairs with. Pass it either as the token query parameter or as Authorization: Bearer <token>; requests without it get 401. The dashboard’s Settings → Other clients card shows the exact URL with a copy button once you have paired.

The token is a password. The endpoint binds to localhost only; if you expose it through a tunnel, make sure the token stays in the URL and the tunnel is private.

Starting the companion for HTTP clients

An HTTP client cannot launch the companion the way a stdio client does. Either:

• Keep a stdio client (Claude Code, OpenCode…) connected: its companion owns the port and serves HTTP at the same time.
• Or run it standalone:

bunx browspark-mcp@latest --http-only

--http-only skips the stdio transport so the process does not exit when stdin closes. Stop it with Ctrl-C; it closes any developer browsers it launched.

Connecting a client

Paste the URL from the dashboard’s Settings page into whichever option of your client asks for an MCP server URL. Start the companion with --http-only first, or have a stdio client running. Nothing else is needed: the client only makes HTTP requests to localhost.

From code, use the MCP SDK’s Streamable HTTP transport:

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const client = new Client({ name: 'my-agent', version: '1.0' });
await client.connect(new StreamableHTTPClientTransport(new URL('http://127.0.0.1:9223/mcp?token=…')));
const { tools } = await client.listTools();

Each HTTP session gets its own MCP server instance and its own agent identity, exactly like a stdio client. The session id travels in the mcp-session-id header; the first request must be a POST that initialises the session.

Sandboxed clients

Some IDEs and hosted agents run MCP servers with no access to your files. For those:

Situation	Use
Client can make localhost HTTP requests	The URL above.
Client can run a command but not read the repo	bun run compile and point it at dist/browspark.
Client can do neither	Not supported; the browser is on your machine, so the client must reach it somehow.