Wiring Every AI Client to BioMate: The MCP Connector Architecture

One tool manifest, eight AI surfaces, zero duplicated logic. How we built a connector layer that lets Claude Code, Claude Desktop, Claude Science, Cursor, Codex CLI, ChatGPT, Slack, and Feishu all drive the same biomedical research execution engine.

The problem

Biomedical research needs real compute. AI clients need a standard protocol.

Running a DESeq2 analysis or an nf-core/sarek variant-calling pipeline isn't something an AI assistant can do inline. It requires containerised environments, high-memory EC2 instances, reference genome indices, and a Nextflow executor that can orchestrate dozens of steps across AWS Batch workers. BioMate provides that infrastructure — but it needs to be reachable from wherever the researcher already works.

The Model Context Protocol (MCP) gives us a standard way to expose capabilities as typed tools that any compliant AI client can discover and call. The challenge was supporting eight very different surfaces — each with its own transport, auth model, and UX contract — without duplicating the tool logic eight times.

The solution is a single canonical tool manifest and a thin adapter per surface. Every connector reads its schema from tools_manifest.py and routes execution through the same dispatch_tool() function that calls BioMate's REST API. The surfaces diverge only in how they transport the call — stdio JSON-RPC, Streamable HTTP, REST Actions, or webhook — not in what they do.

---

Architecture

One manifest, many transports

Green = MCP protocol paths · Grey = REST/webhook paths · Dashed = async / SSE streaming

---

Design principle

The manifest is the contract

Everything starts with mcp/tools_manifest.py. Each tool is a ToolSchema dataclass: name, description, JSON Schema input, backend path, and MCP annotation hints (read_only_hint, open_world_hint, etc.). The manifest has one job — describe the tools precisely enough that any surface can render them correctly.

From that manifest, three things are generated automatically:

• MCP stdio tool list — returned verbatim in the tools/list response
• OpenAPI paths — one path per tool, consumed by ChatGPT Actions and the Coze plugin
• Remote MCP tool defs — the Streamable HTTP endpoint builds its Server from the same manifest at startup

Adding a new tool means adding one ToolSchema entry. Every surface picks it up on next restart, with no changes to adapter code.

---

Tools

19 tools across five categories

---

Surfaces

Eight surfaces, two transport families

Every surface routes through the same tool manifest. What differs is how the call arrives — and how the response is presented back to the user.

---

Get started

Up in two minutes with Claude Code

The fastest path — no OAuth, no server, no ngrok:

1. Get an API key

Log in at biomate.ai → Settings → API Keys → Create key. The key looks like bm_live_….

2. Add to your MCP config

// ~/.mcp.json
{
  "mcpServers": {
    "biomate": {
      "command": "npx",
      "args": ["-y", "@biomate/mcp-server"],
      "env": {
        "BIOMATE_API_URL": "https://api.biomate.ai",
        "BIOMATE_API_KEY": "bm_live_…"
      }
    }
  }
}

3. Try it

# In Claude Code
You: Run DESeq2 differential expression on the FASTQs in
      s3://biomate-demo/rnaseq/, treated vs control, GRCh38.
      Show the top 20 genes when done.

# BioMate searches the catalog, selects dss_rnaseq_multifactor_de,
# submits to AWS Batch, streams phase updates back via watch_run,
# and returns ranked DE genes with log2FC + adjusted p-values.

Dev mode (against a local or staging backend)

// Point at any BioMate instance — no npm package needed
{
  "mcpServers": {
    "biomate-dev": {
      "command": "python3",
      "args": ["/path/to/biomate-connector/mcp/biomate_mcp_server.py"],
      "env": {
        "BIOMATE_API_URL": "https://dev-public.biomate.ai",
        "BIOMATE_API_KEY": "bm_live_…"
      }
    }
  }
}