​
MCP Integration

BioCortex supports the Model Context Protocol (MCP) — an open standard for connecting AI agents to external tool servers. Any MCP-compatible server (local or remote) can extend BioCortex’s tool set without modifying the core framework.

​
Architecture

mcp.json  (per-project or global config)
    ↓
MCPManager  (lifecycle: start / stop / prewarm per-server)
    ↓
UnifiedMCPGateway  (single HTTP endpoint  http://127.0.0.1:3100/mcp)
    ├── biomcp_search_genes
    ├── biomcp_search_variants
    ├── context7_resolve_library_id
    ├── context7_get_library_docs
    ├── filesystem_read_file
    └── pubmed_search_articles
    ↓
MCPProvider  (TTL-cached tool list + call_tool, singleton per gateway URI)
    ↓
BioCortex Agent  (tool descriptions injected into LLM prompt context)

​
Components

ComponentFileResponsibility
MCPManagerbiocortex/mcp/manager.pyStart/stop/restart MCP servers. Mount them to the gateway.
UnifiedMCPGatewaybiocortex/mcp/gateway.pySingle FastMCP HTTP server; each MCP server is mounted with a namespace prefix.
MCPProviderbiocortex/mcp/provider.pyAgent-side client. Lists tools (with TTL cache) and calls them.
MCPServerConfigbiocortex/mcp/config.pyConfig data structures and mcp.json loading with hierarchical merging.

​
Configuration

Create an mcp.json in .biocortex/ inside your project directory, or ~/.biocortex/mcp.json for global settings. Config priority (highest → lowest):
~/.biocortex/mcp.json → .biocortex/mcp.json (project) → package defaults

​
Full Schema

{
  "host": "127.0.0.1",
  "port": 3100,
  "cache_ttl": 60,
  "auto_start": ["biomcp"],
  "servers": {
    "<name>": {
      "type": "stdio",
      "command": "<executable and args>",
      "env": { "ENV_VAR": "value" },
      "description": "Human-readable description"
    },
    "<name2>": {
      "type": "http",
      "uri": "https://my-mcp.example.com/mcp",
      "description": "Remote MCP service"
    }
  }
}
FieldDefaultDescription
host127.0.0.1Gateway bind address.
port3100Gateway HTTP port (auto-increments if occupied).
cache_ttl60Seconds to cache the tool list before re-querying.
auto_start[]Server names to start automatically when BioCortex launches.
servers{}Map of server name → config (see below).
Per-server fields:
FieldDescription
typestdio (local subprocess) or http (remote endpoint).
command(stdio only) Shell command to launch the server.
uri(http only) Full URL of the MCP endpoint.
env(stdio only) Extra environment variables for the subprocess.
descriptionOptional human-readable description.

​
Server Types

​
STDIO Servers

BioCortex spawns and manages the subprocess. Logs are written to ~/.biocortex/logs/mcp/<name>.log. 
{
  "type": "stdio",
  "command": "uv run --with biomcp-python biomcp run"
}
BioCortex handles:
  • Starting the process before the first tool call
  • Pre-warming the connection (reduces first-call latency)
  • Restarting on crash
  • Graceful shutdown when BioCortex exits

​
HTTP Servers

BioCortex connects to an already-running HTTP endpoint. No process management. 
{
  "type": "http",
  "uri": "http://localhost:3200/mcp"
}

​
Pre-configured Servers

The following servers ship in BioCortex’s default config. None are auto_start by default; enable them individually.
NameInstallTools
biomcppip install biomcp-pythonGene/protein/variant/clinical trial search (NCBI, ClinVar, ClinicalTrials.gov)
context7npm i -g @upstash/context7-mcpLibrary/API documentation search
filesystemnpm i -g @modelcontextprotocol/server-filesystemLocal file read/write/list
pubmedpip install mcp-server-pubmedPubMed article search

​
Managing MCP Servers from the CLI

All MCP operations are available via the /mcp slash command inside biocortex cli: 
/mcp                     List all servers and their status
/mcp start biomcp        Start the biomcp server
/mcp stop context7       Stop the context7 server
/mcp restart biomcp      Restart a running server
/mcp tools               List all tools from all running servers
/mcp add myserver 'python my_mcp.py' --autostart --desc 'My custom tools'
/mcp add remote --uri https://my-server.com/mcp
/mcp remove myserver
Tool list output example: 
Running MCP servers: 2

biomcp  [running]  Gene/protein/variant search
  biomcp_search_genes       Search gene information
  biomcp_search_variants    Search variant/SNP data
  biomcp_search_trials      Search ClinicalTrials.gov

context7  [running]  Library documentation
  context7_resolve_library_id   Resolve a library name to ID
  context7_get_library_docs     Get up-to-date library documentation

​
Tool Namespacing

When a server named biomcp is mounted, all its tools are prefixed with biomcp_:
Server tool nameExposed as
search_genesbiomcp_search_genes
search_variantsbiomcp_search_variants
This prevents name collisions when multiple servers expose tools with similar names.

​
Agent Integration

When MCP servers are running, their tools are automatically included in the agent’s LLM prompt as structured tool documentation: 
MCP Tools (external servers):

## biomcp_search_genes
Search for gene information including function, expression, and associated diseases.
Input schema:
  query (string, required): Gene name, symbol, or description.
  organism (string): Species name (default: human).
  limit (integer): Max results (default: 10).

## context7_get_library_docs
Get up-to-date documentation for a software library.
...
The agent can call these tools exactly like any built-in BioCortex tool.

​
Python API

from biocortex.mcp.config import load_mcp_config
from biocortex.mcp.manager import MCPManager
from biocortex.mcp.provider import MCPProvider

# Load and start configured servers
manager = await MCPManager.from_config(project_dir=Path("."))
await manager.start_services(["biomcp", "context7"])

# List available tools
provider = MCPProvider.get_instance(manager.gateway_uri)
tools = await provider.list_tools()
for tool in tools:
    print(tool.name, "—", tool.description)

# Call a tool
result = await provider.call_tool("biomcp_search_genes", {"query": "BRCA1"})

​
Logging

Per-server STDIO logs are written to ~/.biocortex/logs/mcp/<name>.log. This makes it easy to debug individual servers without polluting the main BioCortex output.

​
Installing the MCP Dependency

MCP support requires the fastmcp package: 
pip install fastmcp>=2.0.0
This is listed in requirements.txt and pyproject.toml and is installed automatically with pip install -e ..

​
Next Steps