docs/deployment/mcp-integration.md

MCP Integration Guide

Last Updated: 2025-12-06

This guide covers setting up DeepBoner's MCP (Model Context Protocol) server for integration with Claude Desktop and other MCP clients.

Overview

DeepBoner exposes an MCP server via Gradio's built-in support. This allows Claude Desktop and other MCP-compatible clients to use DeepBoner's search tools directly.

MCP Server URL

When DeepBoner is running:

http://localhost:7860/gradio_api/mcp/

On HuggingFace Spaces:

https://mcp-1st-birthday-deepboner.hf.space/gradio_api/mcp/

Available Tools

Tool	Description
search_pubmed	Search peer-reviewed biomedical literature
search_clinical_trials	Search ClinicalTrials.gov for active/completed trials
search_europepmc	Search Europe PMC preprints and papers
search_all_sources	Search all sources simultaneously with deduplication

Tool Signatures

def search_pubmed(query: str, max_results: int = 10) -> list[Evidence]:
    """Search PubMed for biomedical literature."""

def search_clinical_trials(query: str, max_results: int = 10) -> list[Evidence]:
    """Search ClinicalTrials.gov."""

def search_europepmc(query: str, max_results: int = 10) -> list[Evidence]:
    """Search Europe PMC."""

def search_all_sources(query: str, max_results_per_source: int = 10) -> SearchResult:
    """Search all sources with cross-source deduplication."""

Claude Desktop Setup

1. Start DeepBoner

uv run python src/app.py

2. Configure Claude Desktop

Edit your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the MCP server:

{
  "mcpServers": {
    "deepboner": {
      "url": "http://localhost:7860/gradio_api/mcp/"
    }
  }
}

3. Restart Claude Desktop

Close and reopen Claude Desktop to load the new configuration.

4. Verify Connection

In Claude Desktop, you should see DeepBoner's tools available. Try:

Use the search_pubmed tool to find recent papers on testosterone therapy

Using with HuggingFace Spaces

Point to the deployed Space:

{
  "mcpServers": {
    "deepboner-cloud": {
      "url": "https://mcp-1st-birthday-deepboner.hf.space/gradio_api/mcp/"
    }
  }
}

Note: HuggingFace Spaces may sleep after inactivity. The first request will wake the Space (30-60 second delay).

Tool Implementation

Tools are defined in src/mcp_tools.py:

def search_pubmed(query: str, max_results: int = 10) -> list[Evidence]:
    """Search PubMed for biomedical literature.

    Args:
        query: Search query for PubMed
        max_results: Maximum number of results to return

    Returns:
        List of Evidence objects with citations
    """
    tool = PubMedTool()
    result = tool.search(query, max_results=max_results)
    return result.evidence

Adding New Tools

To expose additional tools via MCP:

1. Add the function to src/mcp_tools.py:

def search_openalex(query: str, max_results: int = 10) -> list[Evidence]:
    """Search OpenAlex for scholarly metadata."""
    tool = OpenAlexTool()
    result = tool.search(query, max_results=max_results)
    return result.evidence

2. Register in Gradio app (src/app.py):

The tools are automatically exposed via Gradio's MCP support when added to the interface.

Troubleshooting

Tools not appearing in Claude Desktop

1. Verify DeepBoner is running:

   curl http://localhost:7860/gradio_api/mcp/
   

2. Check config syntax:

   cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python -m json.tool
   

3. Restart Claude Desktop

Connection refused

• Check DeepBoner is running on port 7860
• Verify no firewall blocking
• Try accessing in browser: http://localhost:7860

Slow responses

• First query loads ML models
• HuggingFace Space may need to wake up
• External APIs have rate limits

Authentication errors

MCP server doesn't require authentication for local use. For production:

• Use API gateway
• Implement auth middleware

Security Considerations

Local Development

Local MCP server is accessible only from localhost by default.

Production

For production deployments:

1. Use HTTPS - Enable TLS via reverse proxy
2. Add authentication - Consider API keys or OAuth
3. Rate limit - Prevent abuse
4. Monitor - Log tool usage

Data Privacy

• Search queries are sent to external APIs (PubMed, etc.)
• Review external API privacy policies
• Don't expose sensitive research queries

Protocol Details

MCP Protocol Version

DeepBoner uses MCP protocol via Gradio 6.x integration.

Request/Response Format

Requests follow the MCP specification:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "search_pubmed",
    "arguments": {
      "query": "testosterone therapy",
      "max_results": 10
    }
  },
  "id": 1
}

Related Documentation

• Docker Deployment
• HuggingFace Spaces
• Component Inventory