SmartAPI Server

Create MCP (Model Context Protocol) servers for one or multiple APIs registered in the SmartAPI registry.

Test PyPI version Python versions License

Overview

The SmartAPI MCP Server enables integration between MCP-compatible clients and APIs registered in the SmartAPI registry. This allows for seamless discovery and interaction with bioinformatics and life sciences APIs through standardized MCP protocols.

Built on top of the AWS Labs OpenAPI MCP Server, this project extends MCP support to the extensive collection of APIs available in the SmartAPI registry, with special focus on bioinformatics and life sciences APIs.

Requirements

• Python 3.10 or higher
• Network access to SmartAPI registry (https://smart-api.info)
• Dependencies: awslabs_openapi_mcp_server>=0.2.12,<1 and fastmcp>=2.14,<3 (awslabs 1.x / fastmcp 3.x are not yet supported — see the dependency notes in pyproject.toml)

Features

• 🔍 SmartAPI Integration: Direct integration with the SmartAPI registry for API discovery
• 🏗️ MCP Protocol Support: Full MCP (Model Context Protocol) server implementation
• 🔄 Async Architecture: Built with modern Python async/await patterns for high performance
• 📖 OpenAPI Validation: Automatic OpenAPI specification parsing and validation
• 🛠️ CLI Interface: Easy-to-use command-line interface with multiple configuration options
• 🧬 Bioinformatics Focus: Pre-configured API sets for bioinformatics and life sciences
• 🧩 Scales to large API sets: Large BioThings sets (e.g. biothings_all, 200+ operations) automatically collapse to ~5 generic tools, avoiding client context overflow without relying on client-side tool deferral
• 🎯 Flexible Configuration: Support for environment variables, arguments, and configuration files
• 🚀 Multiple Transport Modes: Support for both stdio and HTTP transport protocols
• 🧪 Comprehensive Testing: Full test suite with high code coverage

Installation

From PyPI (recommended)

pip install smartapi-mcp

From Source

git clone https://github.com/biothings/smartapi-mcp.git
cd smartapi-mcp
pip install -e .

Development Installation

git clone https://github.com/biothings/smartapi-mcp.git
cd smartapi-mcp
pip install -e ".[dev]"

Using with MCP Clients

Using with uvx (Recommended)

uvx is a tool for running Python applications in isolated environments. This is the recommended way to run smartapi-mcp for MCP client integration:

Installation and Basic Usage

# Install uvx if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh
# or with homebrew on macOS
brew install uv

# Run smartapi-mcp with uvx (automatically installs if needed)
uvx smartapi-mcp --api_set biothings_core

# Run with specific version
uvx [email protected] --api_set biothings_core

# Run with additional arguments
uvx smartapi-mcp --smartapi_id 59dce17363dce279d389100834e43648 --server_name "MyGene MCP Server"

Using with Claude Desktop

To use smartapi-mcp with Claude Desktop, add the following configuration to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "smartapi-biothings-core": {
      "command": "uvx",
      "args": ["smartapi-mcp", "--api_set", "biothings_core", "--server_name", "BioThings Core APIs"]
    },
    "smartapi-mygene": {
      "command": "uvx",
      "args": ["smartapi-mcp", "--smartapi_id", "59dce17363dce279d389100834e43648", "--server_name", "MyGene.info API"]
    },
    "smartapi-myvariant": {
      "command": "uvx",
      "args": ["smartapi-mcp", "--smartapi_id", "09c8782d9f4027712e65b95424adba79", "--server_name", "MyVariant.info API"]
    }
  }
}

Using with Other MCP Clients

For other MCP clients that support external MCP servers, you can typically configure them by providing:

• Command: uvx
• Arguments: ["smartapi-mcp", "--api_set", "biothings_core"] (or other desired arguments)
• Working Directory: Optional, can be any directory
• Environment Variables: Optional, see Environment Variables section

MCP Server Configuration Examples

Basic Bioinformatics Setup

{
  "mcpServers": {
    "biothings-core": {
      "command": "uvx",
      "args": ["smartapi-mcp", "--api_set", "biothings_core"],
      "env": {
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Advanced Multi-API Setup

{
  "mcpServers": {
    "biothings-comprehensive": {
      "command": "uvx",
      "args": [
        "smartapi-mcp",
        "--smartapi_ids",
        "59dce17363dce279d389100834e43648,09c8782d9f4027712e65b95424adba79,8f08d1446e0bb9c2b323713ce83e2bd3",
        "--server_name",
        "Comprehensive Bioinformatics APIs",
        "--log-level",
        "DEBUG"
      ]
    }
  }
}

Large API Sets (biothings_all) — the BioThings facade

All BioThings APIs share the same handful of operations (/query, /{type}/{id}, batch lookups, /metadata/fields). Emitting one MCP tool per (API × operation) for a large set like biothings_all would create 200+ near-duplicate tools and overflow the client's context window.

To avoid this, for large BioThings sets the server exposes a small fixed set of ~5 generic tools where the target API is a parameter:

• list_biothings_apis — discover/search the available APIs (returns data)
• biothings_query — search any API (/query)
• biothings_get / biothings_getbatch — annotation lookup by id(s)
• biothings_fields — list queryable fields for an API

Because the tool list is small and static, this works on every MCP client (no dependency on dynamic tools/list_changed updates).

For a mixed set (BioThings + other API types), the server is hybrid: the BioThings APIs are served through the facade, while any non-BioThings APIs are added as faithful per-API tools in the same server — so no APIs are lost.

{
  "mcpServers": {
    "biothings-all": {
      "command": "uvx",
      "args": ["smartapi-mcp", "--api_set", "biothings_all"]
    }
  }
}

Control the strategy with --facade {auto,on,off} (default auto, which engages the facade once the BioThings APIs in the set reach --facade-threshold, default 10) or the SMARTAPI_FACADE environment variable. Use --facade off to force faithful per-API tools regardless of set size.

A few BioThings APIs expose extra, non-standard endpoints (e.g. SemmedDB's /query/ngd) that the generic facade tools can't reach. These are rare, so by default they're ignored. Pass --facade-strict (or FACADE_STRICT=1) to inspect each BioThings spec at startup and serve any API that has extra endpoints with faithful per-API tools instead — at the cost of slower startup (it downloads the specs upfront).

Development/Testing Setup

{
  "mcpServers": {
    "smartapi-dev": {
      "command": "uvx",
      "args": [
        "smartapi-mcp",
        "--api_set",
        "biothings_test",
        "--log-level",
        "DEBUG"
      ],
      "env": {
        "SMARTAPI_LOG_LEVEL": "DEBUG"
      }
    }
  }
}

Environment Variables for MCP Configuration

You can also use environment variables in your MCP client configuration:

{
  "mcpServers": {
    "smartapi-configured": {
      "command": "uvx",
      "args": ["smartapi-mcp"],
      "env": {
        "SMARTAPI_API_SET": "biothings_core",
        "SERVER_NAME": "BioThings Core MCP Server",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Alternative Installation Methods for MCP Clients

Using pip in a Virtual Environment

If you prefer not to use uvx, you can create a dedicated virtual environment:

# Create and activate virtual environment
python -m venv smartapi-mcp-env
source smartapi-mcp-env/bin/activate  # On Windows: smartapi-mcp-env\Scripts\activate

# Install smartapi-mcp
pip install smartapi-mcp

# Test the installation
smartapi-mcp --api_set biothings_core

Then configure your MCP client to use the full path to the executable:

{
  "mcpServers": {
    "smartapi-biothings": {
      "command": "/path/to/smartapi-mcp-env/bin/smartapi-mcp",
      "args": ["--api_set", "biothings_core"]
    }
  }
}

Using System-wide Installation

# Install globally (not recommended for most users)
pip install smartapi-mcp

# Find the installation path
which smartapi-mcp

MCP client configuration:

{
  "mcpServers": {
    "smartapi-biothings": {
      "command": "smartapi-mcp",
      "args": ["--api_set", "biothings_core"]
    }
  }
}

Troubleshooting MCP Client Integration

Server Not Starting

1. Check uvx installation:

   uvx --version
   

2. Test server manually:

   uvx smartapi-mcp --api_set biothings_core --log-level DEBUG
   

3. Check MCP client logs for specific error messages

Tools Not Appearing in Client

1. Verify server is running with tools registered:

   uvx smartapi-mcp --api_set biothings_core --log-level DEBUG 2>&1 | grep -i "tool"
   

2. Check API connectivity:

   curl -s https://mygene.info/v3/metadata | head -20
   

3. Try a smaller API set first:

   uvx smartapi-mcp --smartapi_id 59dce17363dce279d389100834e43648
   

Performance Issues

• Use specific SmartAPI IDs instead of large API sets
• Enable only the APIs you actually need
• Consider using HTTP transport for better performance with multiple concurrent requests:

  {
    "mcpServers": {
      "smartapi-http": {
        "command": "uvx",
        "args": ["smartapi-mcp", "--api_set", "biothings_core", "--transport", "http", "--port", "8001"]
      }
    }
  }
  

Quick Start

Command Line Usage

Start with a predefined API set (recommended)

# Use BioThings core APIs (MyGene, MyVariant, MyChem, MyDisease, MyGeneSet)
smartapi-mcp --api_set biothings_core

# Use all BioThings APIs (with some exclusions)
smartapi-mcp --api_set biothings_all

Start with specific SmartAPI IDs

# Single API
smartapi-mcp --smartapi_id 59dce17363dce279d389100834e43648

# Multiple APIs
smartapi-mcp --smartapi_ids "59dce17363dce279d389100834e43648,09c8782d9f4027712e65b95424adba79"

Start with HTTP transport (instead of stdio)

# HTTP mode on localhost:8000 (default)
smartapi-mcp --api_set biothings_core --transport http

# Custom host and port
smartapi-mcp --api_set biothings_core --transport http --host 0.0.0.0 --port 9000

Advanced options

# Custom logging level
smartapi-mcp --api_set biothings_core --log-level DEBUG

# Custom server name
smartapi-mcp --api_set biothings_core --server_name "My Custom MCP Server"

# Query-based API discovery
smartapi-mcp --smartapi_q "tags.name=biothings"

# Exclude specific APIs
smartapi-mcp --api_set biothings_all --smartapi_exclude_ids "api_id_1,api_id_2"

Python API Usage

import asyncio
from smartapi_mcp import (
    get_smartapi_ids,
    load_api_spec,
    get_mcp_server,
    get_merged_mcp_server,
    PREDEFINED_API_SETS
)

async def main():
    # Get SmartAPI IDs using a query
    smartapi_ids = await get_smartapi_ids("tags.name=biothings")
    print(f"Found {len(smartapi_ids)} APIs matching the query")

    # Load API specification for a specific SmartAPI
    api_spec = load_api_spec("59dce17363dce279d389100834e43648")  # MyGene.info
    print(f"Loaded API: {api_spec.get('info', {}).get('title', 'Unknown')}")

    # Create MCP server for a single API
    server = await get_mcp_server(
        smartapi_id="59dce17363dce279d389100834e43648",
        server_name="MyGene MCP Server"
    )

    # Create merged MCP server for multiple APIs (recommended approach)
    merged_server = await get_merged_mcp_server(
        api_set="biothings_core",  # Use predefined set
        server_name="BioThings Core MCP Server"
    )

    # Or with specific SmartAPI IDs
    merged_server = await get_merged_mcp_server(
        smartapi_ids=[
            "59dce17363dce279d389100834e43648",  # MyGene.info
            "09c8782d9f4027712e65b95424adba79",  # MyVariant.info
        ],
        server_name="Custom MCP Server"
    )

    # Show available predefined API sets
    print(f"Available API sets: {PREDEFINED_API_SETS}")

    # Run server with stdio transport (default for MCP)
    merged_server.run()

    # Or run with HTTP transport
    # merged_server.run(transport="http", host="localhost", port=8000)

if __name__ == "__main__":
    asyncio.run(main())

API Examples

BioThings Core APIs

When you use --api_set biothings_core, you get access to these powerful bioinformatics APIs:

1. MyGene.info (59dce17363dce279d389100834e43648): Gene annotation and information
2. MyVariant.info (09c8782d9f4027712e65b95424adba79): Variant annotation and information
3. MyChem.info (8f08d1446e0bb9c2b323713ce83e2bd3): Chemical and drug information
4. MyDisease.info (671b45c0301c8624abbd26ae78449ca2): Disease information and associations
5. MyGeneSet.info (85139f4dccfcefa3ac3042372066916d): Collect, share and save genes

Usage with MCP Clients

Once the server is running, MCP-compatible clients can discover and use the available tools. Each API endpoint becomes an available MCP tool with:

• Tool discovery: Clients can list all available API endpoints
• Parameter validation: Automatic parameter validation based on OpenAPI specs
• Rich descriptions: Each tool includes detailed descriptions from the API documentation
• Error handling: Proper error responses for invalid requests

Configuration

The server supports multiple configuration methods:

Environment Variables

# SmartAPI configuration
export SMARTAPI_ID="59dce17363dce279d389100834e43648"
export SMARTAPI_IDS="id1,id2,id3"
export SMARTAPI_Q="tags.name=biothings"
export SMARTAPI_API_SET="biothings_core"
export SMARTAPI_EXCLUDE_IDS="exclude_id1,exclude_id2"

# BioThings facade strategy (see "Large API Sets" above)
export SMARTAPI_FACADE="auto"     # auto | on | off
export FACADE_THRESHOLD="10"      # min BioThings APIs before 'auto' uses the facade
export FACADE_STRICT="false"      # inspect specs; serve APIs with extra endpoints per-API

# Server configuration
export SERVER_NAME="My SmartAPI MCP Server"
export TRANSPORT="http"
export HOST="localhost"
export PORT="8000"

# Then run without arguments
smartapi-mcp

Command Line Arguments

All configuration can be provided via command line arguments (see Quick Start section above).

Predefined API Sets

The following predefined API sets are available:

• biothings_core: Core BioThings APIs (MyGene, MyVariant, MyChem, MyDisease, MyGeneSet)
• biothings_test: Core APIs plus SemmedDB (useful for testing)
• biothings_all: All BioThings APIs (with some exclusions for stability)

Configuration Priority

1. Command line arguments (highest priority)
2. Environment variables
3. Default values (lowest priority)

Development

Setting up Development Environment

# Clone the repository
git clone https://github.com/biothings/smartapi-mcp.git
cd smartapi-mcp

# Install development dependencies
pip install -e ".[dev]"

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=smartapi_mcp --cov-report=html

# Run specific test file
pytest tests/test_basic.py

Code Quality

# Check and fix linting issues
ruff check .
ruff check . --fix

# Format code
ruff format .

Building the Package

# Build source and wheel distributions
python -m build

# Check the built package
twine check dist/*

Publishing to PyPI

Manual Publishing

# Build the package
python -m build

# Upload to Test PyPI (optional)
twine upload --repository testpypi dist/*

# Upload to PyPI
twine upload dist/*

Automated Publishing

This repository includes GitHub Actions workflows for automated testing and publishing:

• Test Workflow (.github/workflows/test.yml): Runs on every push and pull request
• Publish Workflow (.github/workflows/publish.yml): Publishes to PyPI on release

To publish a new version:

1. Update the version in pyproject.toml and smartapi_mcp/__init__.py
2. Commit the version changes
3. Create and push a git tag: git tag v0.2.0 && git push origin v0.2.0
4. Create a new release on GitHub
5. The publish workflow will automatically build and upload to PyPI

Manual Workflow Trigger

You can also manually trigger the publish workflow to upload to Test PyPI:

1. Go to the Actions tab in your GitHub repository
2. Select "Publish Python Package"
3. Click "Run workflow"
4. Choose "Publish to Test PyPI" option

Contributing

We welcome contributions! Please see our contributing guidelines for details.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for your changes
5. Ensure tests pass (pytest)
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

Troubleshooting

Common Issues

No tools or resources registered

WARNING: No tools or resources were registered. This might indicate an issue with the API specification or authentication.

Solution: This usually happens when:

• The SmartAPI ID is invalid or the API is down
• The OpenAPI specification has validation errors
• Network connectivity issues

Try with a known working API set: smartapi-mcp --api_set biothings_core

Server fails to start

Check your Python version: Requires Python 3.10+

python --version

Verify installation:

pip show smartapi-mcp

HTTP mode connection issues

If using HTTP transport mode and clients can't connect:

• Check if the port is available: netstat -an | grep :8000
• Try binding to all interfaces: --host 0.0.0.0
• Check firewall settings

Getting Help

1. Enable debug logging: --log-level DEBUG
2. Check the GitHub Issues
3. Contact us at [email protected]

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Related Projects

• SmartAPI Registry - Registry of biomedical and life sciences APIs
• Model Context Protocol (MCP) - Standard protocol for AI model-tool integration
• BioThings APIs - High-performance bioinformatics APIs
• AWS Labs OpenAPI MCP Server - Base MCP server framework

Citation

If you use SmartAPI MCP Server in your research or applications, please cite:

SmartAPI MCP Server: Bridging Bioinformatics APIs with Model Context Protocol
BioThings Team. (2024). https://github.com/biothings/smartapi-mcp

Support

For questions and support:

• 📖 Documentation: README
• 🐛 Bug Reports: GitHub Issues
• 💬 Questions: GitHub Discussions
• 📧 Email: [email protected]

---

SmartAPI MCP Server is developed and maintained by the BioThings Team at The Scripps Research Institute.