MCP Integration Guide - Sunholo Patterns

Note: This document covers the Sunholo VACRoutes MCP integration pattern.

For other MCP documentation:

Overview

This guide documents the enhanced Model Context Protocol (MCP) integration in Aitana Backend using Sunholo patterns for the FastAPI server implementation.

Key Improvements

1. Simplified App Creation

Using VACRoutesFastAPI.create_app_with_mcp() for one-line setup:

app, vac_routes = VACRoutesFastAPI.create_app_with_mcp(
    title="Aitana Backend API",
    stream_interpreter=vac_stream_with_assistant_support,
    app_lifespan=app_lifespan,
    enable_a2a_agent=True,
    additional_routes=additional_routes,
    add_langfuse_eval=True
)

2. Dynamic Tool Registration

Register MCP tools using the decorator pattern:

@vac_routes.add_mcp_tool
async def demo_reverse_text(text: str) -> str:
    """Reverse the input text as a demo MCP tool."""
    return text[::-1]

3. Dual MCP Server Support

  • Main MCP Server: /mcp - Sunholo’s built-in MCP with dynamic tools
  • Aitana MCP Server: /aitana-mcp - Custom Aitana tools (9 production tools)

4. Enhanced SSE Support

Automatic Server-Sent Events endpoints for streaming:

  • /vac/streaming/{vector_name}/sse
  • /vac/assistant/{assistant_id}/sse

5. Interactive Test Page

Access the test dashboard at http://localhost:1956/test to:

  • Test MCP tools interactively
  • Verify streaming functionality
  • Check assistant API endpoints

Available MCP Tools

Tool Categories

1. Native API Tools

  • Direct Python functions in backend/tools/
  • Called directly by tool orchestrator
  • Examples: google_search, ai_search, file-browser

2. Registered MCP Servers (Pre-configured)

  • Defined in backend/tools/mcp_servers.py
  • Available as named tools (mcp_demo, mcp_database)
  • Server code in backend/tools/mcp_tools/

3. Dynamic MCP Tools (external_mcp)

  • Runtime configuration via toolConfigs
  • Connect to any MCP server dynamically
  • See Architecture Guide

Aitana Production Tools (via MCP)

Processing Tools

  • ai_search - Vertex AI semantic search
  • extract_files - Extract content from GCS files
  • google_search - Web search with AI analysis
  • structured_extraction - Extract structured data using schemas
  • url_processing - Process and analyze web URLs
  • user_history - Search user chat history

Model Tools

  • gemini_model - Google Gemini models
  • anthropic_smart_model - Anthropic Claude models
  • smart_stream_model - Unified streaming models

API Endpoints

Core Endpoints

  • /health/detailed - Detailed health check
  • /mcp/debug - MCP status and tools info
  • /test - Interactive test page

VAC Endpoints

  • /vac/streaming/{vector_name} - Plain text streaming
  • /vac/streaming/{vector_name}/sse - SSE streaming
  • /vac/assistant/{assistant_id} - Assistant interaction
  • /vac/assistants - List all assistants

MCP Protocol

  • /mcp - Main MCP server (JSON-RPC 2.0)
  • /aitana-mcp - Aitana MCP server

Testing MCP Tools

Test Different Tool Types

  1. Native API Tools: Direct endpoint calls
  2. Registered MCP: /direct/tools/mcp/{server_id}/call
  3. Dynamic MCP: Configure via external_mcp

For complete testing guide, see MCP Architecture - Testing

Using curl

# List all tools
curl -X POST http://localhost:1956/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

# Call a tool
curl -X POST http://localhost:1956/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "demo_reverse_text",
      "arguments": {"text": "Hello MCP!"}
    }
  }'

Using the Test Page

  1. Navigate to http://localhost:1956/test
  2. Click “MCP Tools” tab
  3. Select a tool from the dropdown
  4. Edit the JSON arguments
  5. Click “Call Tool” to execute

Migration Notes

From Old Pattern

# Old pattern
vac_routes = VACRoutesFastAPI(
    app=app,
    stream_interpreter=interpreter,
    additional_routes=routes
)

To New Pattern

# New pattern (Sunholo 0.144.5)
app, vac_routes = VACRoutesFastAPI.create_app_with_mcp(
    title="App Title",
    stream_interpreter=interpreter,
    additional_routes=routes
)

Benefits

  1. Cleaner Code: Less boilerplate, automatic MCP setup
  2. Better Integration: Unified MCP server with all tools
  3. Dynamic Tools: Add tools at runtime with decorators
  4. SSE Support: Built-in Server-Sent Events for streaming
  5. Backward Compatible: Existing endpoints preserved

Troubleshooting

MCP Server Not Working

Check the debug endpoint:

curl http://localhost:1956/mcp/debug

Tools Not Available

Verify tool registration:

# In app_fastapi.py
@vac_routes.add_mcp_tool
async def your_tool(...):
    ...

Streaming Issues

  • Use /sse endpoints for Server-Sent Events
  • Check CORS settings if calling from browser
  • Verify streaming is enabled in request body

Configuration

Environment Variables

# Required for Aitana MCP tools
GOOGLE_CLOUD_PROJECT=your-project
GOOGLE_CLOUD_LOCATION=global
ANTHROPIC_API_KEY=your-key

Dependencies

# pyproject.toml
sunholo[gcp,http,anthropic]==0.144.5
fastmcp>=1.7.1

Further Reading