Connecting AI Clients

The server speaks stdio for local clients (which spawn it as a subprocess) and streamable HTTP for remote web clients. The fastest path for local clients is the one-shot installer; manual configuration for each client is shown below.

One-shot installer (Claude Code, Claude Desktop, Codex)

uv run bionodulo-mcp install \
  --clerk-secret-key sk_live_... \
  --user-email you@example.com

This writes/merges configuration for every detected client:

• Codex CLI, Codex IDE extension & ChatGPT desktop app → ~/.codex/config.toml (a [mcp_servers.bionodulo] section with startup_timeout_sec = 30 and tool_timeout_sec = 120). Verify with codex mcp list, and use /mcp in a Codex session to confirm the tools are visible.
• Claude Desktop → claude_desktop_config.json (an existing config is merged; an invalid one is backed up first). Restart Claude Desktop afterwards.
• Claude Code → registered at user scope via claude mcp add. If the claude CLI isn’t on PATH, the installer prints the exact manual command instead. Verify with claude mcp list.

Use --client claude-code|claude-desktop|codex to install just one (the default is --client all). Both flags fall back to the CLERK_SECRET_KEY and BIONODULO_USER_EMAIL environment variables; if neither is set, the values are written as placeholders you must fill in by hand.

Manual configuration

codex mcp add bionodulo \
  --env CLERK_SECRET_KEY=sk_live_... \
  --env BIONODULO_USER_EMAIL=you@example.com \
  -- uv --directory /path/to/BioNodulo/mcp run bionodulo-mcp

claude mcp add bionodulo --scope user \
  --env CLERK_SECRET_KEY=sk_live_... \
  --env BIONODULO_USER_EMAIL=you@example.com \
  -- uv --directory /path/to/BioNodulo/mcp run bionodulo-mcp

{
  "mcpServers": {
    "bionodulo": {
      "command": "uv",
      "args": ["--directory", "/path/to/BioNodulo/mcp", "run", "bionodulo-mcp"],
      "env": {
        "CLERK_SECRET_KEY": "sk_live_...",
        "BIONODULO_USER_EMAIL": "you@example.com"
      }
    }
  }
}

On all clients, replace /path/to/BioNodulo/mcp with the absolute path to the mcp/ directory in your checkout of the repository.

ChatGPT web & Claude.ai web (remote connectors)

Web chat clients can’t spawn local processes — they need the server exposed over HTTPS with the streamable-HTTP transport:

# 1. Run the server over HTTP (set a token to protect the endpoint)
export BIONODULO_MCP_TOKEN=$(openssl rand -hex 32)
export CLERK_SECRET_KEY=sk_live_...
export BIONODULO_USER_EMAIL=you@example.com
uv run bionodulo-mcp serve --transport http --host 0.0.0.0 --port 8787
 
# 2. Expose it publicly, e.g. with a Cloudflare tunnel
cloudflared tunnel --url http://localhost:8787

Then, using https://<your-host>/mcp:

• ChatGPT: Settings → Apps → Advanced → enable Developer Mode → Create app, paste the /mcp URL, choose authentication (bearer token via advanced settings, or none for a local tunnel you control).
• Claude.ai: Customize → Connectors → Add custom connector, paste the /mcp URL.

Verify: after adding the connector, ask the chat to “list my BioNodulo runs” — it should call list_runs and return your team’s recent runs.

Next

• Tool Reference