Skip to content

BioMCP with MCP Client Tutorial

Overview

This tutorial explains how to integrate BioMCP with MCP clients programmatically. The Model Context Protocol (MCP) enables applications to interact with BioMCP as a specialized tool server, providing structured access to biomedical data sources.

Key Features

  • STDIO Communication: BioMCP uses standard input/output for MCP communication
  • Tool Discovery: Clients can discover available tools through the MCP interface
  • Resource Access: Provides access to BioMCP resources and instructions
  • Standard Protocol: Follows the MCP 1.0 specification for compatibility with clients

Main Components

The MCP integration relies on these key components:

  1. MCP Client

  2. Python client from the mcp package

  3. Handles communication with the BioMCP server

  4. BioMCP Server

  5. Started as a subprocess with the biomcp run command

  6. Exposes biomedical data tools through the MCP interface

  7. Tool Invocation

  8. Execute biomedical queries using standardized tool calls
  9. Process structured responses for application integration

Basic Usage Pattern

Integrating with BioMCP through MCP follows this pattern:

  1. Start the BioMCP server as a subprocess
  2. Create an MCP client session to communicate with the server
  3. Discover available tools and resources
  4. Call tools with appropriate parameters
  5. Process the returned content

Example Code

Here's a minimal example showing how to connect to BioMCP using the Python MCP client:

import asyncio
from mcp.client.session import ClientSession
from mcp.client.stdio import StdioServerParameters, stdio_client

async def connect_to_biomcp():
    # Configure the BioMCP server
    server_params = StdioServerParameters(
        command="uv",
        args=["run", "--with", "biomcp-python", "biomcp", "run"]
    )

    # Connect to the server
    async with (
        stdio_client(server_params) as (read, write),
        ClientSession(read, write) as session
    ):
        # Initialize the session
        await session.initialize()

        # List available tools
        tool_result = await session.list_tools()
        print(f"Available tools: {[t.name for t in tool_result.tools]}")

        # Call a tool example (variant details)
        result = await session.call_tool(
            "variant_details",
            {"variant_id": "rs113488022"}
        )

        if not result.isError and result.content:
            # Access the text content from the first content block
            content = result.content[0].text
            print(f"Result snippet: {content[:100]}...")

# Run the example
if __name__ == "__main__":
    asyncio.run(connect_to_biomcp())

For a complete example of integrating BioMCP with an MCP client, see:

BioMCP MCP Integration Example Script

Available Tools

BioMCP exposes these tools through the MCP interface:

  1. Article Tools

  2. article_searcher: Search biomedical literature

  3. article_details: Get details for a specific article

  4. Trial Tools

  5. trial_searcher: Search clinical trials

  6. trial_protocol: Get trial protocol details
  7. trial_locations: Get trial location information
  8. trial_outcomes: Get trial outcome data

  9. trial_references: Get trial references

  10. Variant Tools

  11. variant_searcher: Search genetic variants
  12. variant_details: Get detailed variant information

Integration Options

There are several ways to integrate BioMCP with MCP clients:

  1. Direct Python Integration: Use the example above in Python applications
  2. Language-Specific Clients: Implement MCP clients in other languages (JavaScript, etc.)
  3. AI Assistant Integration: Configure LLM platforms to use BioMCP as a tool provider

Troubleshooting

Common issues when integrating BioMCP:

  • Server Not Found: Ensure BioMCP is installed and the command path is correct
  • Connection Errors: Check subprocess management and STDIO handling
  • Tool Errors: Verify tool names and parameter formats match BioMCP's expectations

Next Steps

For more information on MCP integration with BioMCP: