Installation & Configuration

The MCP server lives in the mcp/ directory of the BioNodulo repository and is managed with uv.

Prerequisites

uv — see the uv installation docs.
Python 3.13 — the package requires Python ≥ 3.13. You don’t need to install it yourself; uv sync resolves and downloads it automatically.

Install

cd mcp
uv sync

This installs the package and its dependencies (fastmcp, httpx) and makes the bionodulo-mcp command available via uv run.

Configuration

The server is configured entirely through environment variables:

Env var	Purpose
`BIONODULO_API_URL`	Cloud API base URL (default `https://bionodulo.com`)
`BIONODULO_AUTH_TOKEN`	A pre-minted Clerk session JWT (short-lived)
`CLERK_SECRET_KEY`	Clerk backend secret — enables automatic token refresh
`BIONODULO_USER_EMAIL` / `BIONODULO_USER_ID`	Which Clerk user to mint session tokens for
`BIONODULO_TEAM_ID`	Optional `X-Team-Id` override (defaults to the user’s first team)
`BIONODULO_DESKTOP_URL`	Local desktop backend (default `http://127.0.0.1:8765`)
`BIONODULO_DESKTOP`	Set to `0` (or `false`/`no`) to disable the `desktop_*` tools
`BIONODULO_MCP_TOKEN`	Require this bearer token on the HTTP transport

Authentication

The cloud API accepts a Clerk session JWT as a bearer token. Session JWTs are short-lived (~minutes), so there are two ways to authenticate:

Recommended: automatic refresh. Set CLERK_SECRET_KEY plus BIONODULO_USER_EMAIL (or BIONODULO_USER_ID). The server uses the Clerk Backend API to mint 10-minute session tokens from the user’s most recently active session, caches them, and refreshes them shortly before expiry — entirely server-side. When choosing among active sessions it prefers a session with an active organization, because tokens minted from it carry org_id/org_role claims that several endpoints require. If minting fails (e.g. the session was revoked), the server re-resolves the session once.
Static token. Set BIONODULO_AUTH_TOKEN to a pre-minted session JWT. Simple, but the token expires after minutes and must be replaced manually. When both are set, the static token takes precedence.

The user must have signed in to bionodulo.com at least once — otherwise there is no active Clerk session to mint tokens from.

Running the server

The default transport is stdio, which is what local clients (Claude Desktop, Claude Code, Codex) expect when they spawn the server as a subprocess:

uv run bionodulo-mcp
# or explicitly:
uv run bionodulo-mcp serve --transport stdio

For remote clients, serve the streamable HTTP transport instead:

export BIONODULO_MCP_TOKEN=$(openssl rand -hex 32)
uv run bionodulo-mcp serve --transport http --host 0.0.0.0 --port 8787

This exposes the MCP endpoint at http://<host>:8787/mcp (the --path defaults to /mcp, and --host/--port default to 127.0.0.1:8787). When BIONODULO_MCP_TOKEN is set, every MCP request over HTTP must carry Authorization: Bearer <token>. The stdio transport never uses this — the parent process owns the pipe.

See Connecting AI Clients for wiring this up to ChatGPT web and Claude.ai web.

Testing the connection

The repo ships a live end-to-end test that exercises the read-only tools against the real cloud API using the FastMCP in-process client (mutating tools like submit_run are intentionally not called):

CLERK_SECRET_KEY=sk_live_... BIONODULO_USER_EMAIL=you@example.com \
  uv run python scripts/test_live.py

It lists the registered tools, prompts and resources, calls the read-only cloud tools, reads the three resources, probes desktop_status (expected to fail gracefully if no desktop app is running), and prints ALL GOOD on success.

Overview Connecting AI Clients