Connecting agents
Every agent connects to the same address: http://127.0.0.1:4242/mcp,
unless you started the server somewhere else. There is no login or token.
The steps are always the same:
- Start the server and the page. For the demo in this repository,
bunx nx dev demo-mcpdoes both. - Bring the page’s tab to the front. A hidden tab gets no animation frames, so NiiVue cannot draw, and a screenshot would be blank.
- Add the address to your agent, as shown below.
- Ask for something: “go to the left hippocampus”, “cut an axial plane through the crosshair”, “send me a screenshot”.
The examples call the server niivue. Any name works: it only changes how
the agent labels the tools, such as mcp__niivue__go_to_region in Claude
Code.
http://127.0.0.1:4242/ is a plain status page listing the connected
tabs, with * on the one that answers. When something does not work,
look there first.
Claude Code
claude mcp add --transport http niivue http://127.0.0.1:4242/mcpThis adds the server for you, in this folder. Add --scope user to have
it everywhere, or --scope project to write a .mcp.json that others on
the project pick up:
{ "mcpServers": { "niivue": { "type": "http", "url": "http://127.0.0.1:4242/mcp" } }}Type /mcp in a session to see whether the server connected and which
tools it has. claude mcp remove niivue takes it out again.
To run one request without a session, save that JSON as niivue.json and
allow the tools up front:
claude -p --mcp-config niivue.json --strict-mcp-config \ --allowedTools "mcp__niivue__*" --output-format text \ "Load the template, go to the left hippocampus, and tell me what is under the crosshair."--strict-mcp-config ignores your other servers, so the run behaves the
same every time.
Claude desktop app
The desktop app’s connector settings only take servers on HTTPS, so a
server on your own machine goes through the mcp-remote bridge instead.
Add it to claude_desktop_config.json (Settings, Developer, Edit Config;
on macOS it is in ~/Library/Application Support/Claude/):
{ "mcpServers": { "niivue": { "command": "/opt/homebrew/bin/npx", "args": ["-y", "mcp-remote", "http://127.0.0.1:4242/mcp"] } }}Use the full path to npx, which which npx prints: the app does not
start from a shell, so it cannot find tools that Homebrew or nvm put on
your PATH. Quit and reopen the app after editing the file. The server
shows up under the tools icon in a new chat.
Codex CLI
codex mcp add niivue --url http://127.0.0.1:4242/mcpThat writes this to ~/.codex/config.toml:
[mcp_servers.niivue]url = "http://127.0.0.1:4242/mcp"Codex may say the server needs a login. It does not, so skip
codex mcp login. codex mcp list shows the entry, and /mcp in a
session shows the tools.
Gemini CLI
gemini mcp add --transport http niivue http://127.0.0.1:4242/mcpThis writes .gemini/settings.json in the current folder; add
--scope user to write ~/.gemini/settings.json instead.
/mcp in a session lists the servers and their tools. Gemini asks before
each tool call unless you add --trust to the add command.
VS Code with GitHub Copilot
From a shell:
code --add-mcp '{"name":"niivue","type":"http","url":"http://127.0.0.1:4242/mcp"}'Or by hand, in .vscode/mcp.json. Note that the key is servers, not
mcpServers:
{ "servers": { "niivue": { "type": "http", "url": "http://127.0.0.1:4242/mcp" } }}Open the Chat view and choose Agent mode: the tools appear in the tools
picker. The MCP: List Servers command starts and stops the server and
shows its output.
Cursor
In .cursor/mcp.json for one project, or ~/.cursor/mcp.json for all of
them:
{ "mcpServers": { "niivue": { "url": "http://127.0.0.1:4242/mcp" } }}Cursor’s MCP settings show a green dot once it has the tool list. Use the tools from Agent mode in the chat pane.
Windsurf
In ~/.codeium/windsurf/mcp_config.json, which the Cascade panel’s MCP
settings also open:
{ "mcpServers": { "niivue": { "serverUrl": "http://127.0.0.1:4242/mcp" } }}Press refresh in those settings after editing the file.
Any other agent
An agent that takes an HTTP (or “streamable HTTP”) server needs only the
address. One that can only start local commands reaches the server through
mcp-remote, as the Claude desktop app does:
{ "command": "npx", "args": ["-y", "mcp-remote", "http://127.0.0.1:4242/mcp"]}The same bridge helps an agent that only speaks the older SSE transport, which the server does not offer.
Your own program
With the TypeScript SDK:
import { Client } from '@modelcontextprotocol/sdk/client/index.js'import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'
const client = new Client({ name: 'my-agent', version: '0.1.0' })await client.connect(new StreamableHTTPClientTransport(new URL('http://127.0.0.1:4242/mcp')))
const where = await client.callTool({ name: 'where_am_i', arguments: {} })client.getInstructions() returns what the app told agents about itself,
such as which files its server has.
With the Python SDK (pip install mcp):
from mcp import ClientSessionfrom mcp.client.streamable_http import streamablehttp_client
async with streamablehttp_client("http://127.0.0.1:4242/mcp") as (read, write, _): async with ClientSession(read, write) as session: await session.initialize() where = await session.call_tool("where_am_i", {})A program that opens several pages can pass tab, the id of the tab to
ask, to any tool that works on a page. list_tabs names the tabs.
Checking the connection without an agent
The MCP Inspector is a small web app for calling tools by hand:
bunx @modelcontextprotocol/inspectorChoose Streamable HTTP, enter http://127.0.0.1:4242/mcp and connect. The
Tools tab lists every tool. Calling where_am_i is a good first check.
When something does not work
“No NiiVue tab is connected.” The server is running but no page is connected to it. Open the page, or bring its tab to the front and wait for it to connect. The rest of the message, if the app set one, says which address to open.
A call times out after 15 seconds, or the screenshot is blank. The page’s tab is hidden or covered, and NiiVue cannot draw in it. Bring the tab to the front. For runs nobody watches, use a headless browser such as Playwright’s Chromium.
The agent cannot connect, with an “Invalid Host header” error. The
agent reached the server under a name the server does not know, such as a
name from /etc/hosts or a tunnel. Add it, with its port, to
allowedHosts in startServer.
The agent connects, but the page cannot. If the server log says
“refused a socket from” an address, the page is served from somewhere
other than this machine: add its origin to allowedOrigins. A page served
over HTTPS cannot reach the server’s plain ws:// address at all, so it
needs the /agent proxy. See
Serving the page from another address.
A new tool or argument is missing. In this repository, the demo uses
the built package. Restart bunx nx dev demo-mcp, which builds it first.
The wrong tab answers. Ask the agent to list the tabs and use the one you want, or to name the tab on each call.