biomed-agent

Biomedical Agent is a general-purpose knowledge assistant for biomedical questions. It connects to multiple MCP data sources (OpenTargets, Monarch, MyGene, MyChem, and MyDisease) through MCP clients and orchestrates tool usage to produce synthesized answers with confidence, citations, and limitations. You can interact with it via a CLI or a Streamlit web UI. The CLI provides commands to list available servers and tools, perform queries, and request detailed JSON outputs, while the Streamlit UI offers a graphical chat/direct query experience and the ability to inspect sources and limitations for each response. To get started, ensure your local MCP stack is running and the biomedical agent server is active, then use the CLI or UI to pose questions like: “What is the mechanism of action of vemurafenib?” or “Which genes are associated with Parkinson disease?”.

Tools and capabilities include: listing available MCP servers and tools, querying cross-source biomedical data, direct tool calls to specific MCPs (e.g., opentargets, monarch, mygene, mychem, mydisease), and receiving structured metadata such as confidence, citations, and limitations for each answer. The system reasons across tools, normalizes observations, and returns an integrated response with provenance and traceable sources.

Prerequisites

• Python 3.12 or 3.13
• uv (dependency manager) installed locally
• Local MCP servers installed for OpenTargets, Monarch, MyGene, MyChem, and MyDisease

Installation steps

1. Install Python and uvx-compatible tooling

• Ensure Python 3.12/3.13 is installed on your system.
• Install uvx if not already available in your environment.

2. Install the Biomedical Agent package (biomed-agent)

• Clone or download the repository containing the Biomedical Agent MCP server.
• Optionally create and activate a virtual environment: python -m venv venv source venv/bin/activate # macOS/Linux .\venv\Scripts\activate # Windows
• Install dependencies (adapt to your environment, typically via a requirements.txt or pyproject.toml): pip install -r requirements.txt

3. Run the server with uvx

• Start the Biomedical Agent MCP server using uvx. This example assumes the package name is biomed-agent: uvx biomed-agent
• If your setup requires a module path, you may also run the equivalent command via the UI/module as described in the repository's guidance.

4. Configure environment variables

• Create or copy the environment configuration from .env.example to .env after installing dependencies: cp .env.example .env
• Edit .env to include your API keys and local MCP server paths as needed (OpenTargets, Monarch, MyGene, MyChem, MyDisease endpoints).

5. Verify the setup

• Use the CLI to list servers and tools to ensure the Biomedical Agent is registered and functional: uv run python -m ui.cli list-servers uv run python -m ui.cli list-tools

Note: If you are running all MCP components locally, ensure that each MCP service is up and reachable by the agent. Consult the repository documentation for any additional configuration steps specific to your environment.

Tips and common issues:

• Ensure all prerequisite MCP servers (OpenTargets, Monarch, MyGene, MyChem, MyDisease) are running locally before starting the Biomedical Agent.
• The environment file (.env) should contain API keys and paths to the local MCP servers; missing keys can lead to degraded performance or failures in tool calls.
• If the agent cannot reach a specific MCP source, check network/firewall settings and verify that the service is listening on the expected host/port.
• The agent returns structured metadata including confidence, citations, and limitations; use this to assess reliability and traceability of the answers.
• For Streamlit usage, after starting the server, you can access the UI and select available servers in the sidebar, then connect and chat or query directly. The CLI provides scripted and repeatable interactions, which are useful for automation and testing.