MCP Documentation Index

Overview

Aitana implements Model Context Protocol (MCP) in multiple ways to enable tool integration with AI assistants. This index helps you find the right documentation for your needs.

Quick Navigation

🚀 I want to…

Use MCP with Claude Desktop/Code

➡️ MCP Claude Integration Guide

  • Setup instructions for Claude Desktop and Claude Code
  • Launcher scripts and configuration
  • Client detection features

Understand the complete MCP architecture

➡️ MCP Complete Architecture Guide

  • Full technical overview
  • Terminology explanations
  • API flow analysis
  • Troubleshooting guide

Get quick commands and setup

➡️ MCP Quick Reference

  • Common commands
  • Quick setup steps
  • Key endpoints
  • Test examples

Understand FastAPI/Sunholo integration

➡️ MCP Integration Guide - Sunholo Patterns

  • VACRoutesFastAPI patterns
  • Decorator-based tool registration
  • SSE streaming support

Review technical implementation details

➡️ Backend MCP Integration Architecture

  • Server implementations
  • Client detection system
  • stdio compatibility layer
  • Performance considerations

Key Concepts Summary

MCP Integration Types

Type Description Use Case Documentation
Claude Direct stdio server for Claude Desktop/Code Using Aitana tools in Claude Claude Integration
Native API Tools Direct Python functions Backend services Architecture Guide
Registered MCP Pre-configured MCP servers Permanent integrations Complete Guide
Dynamic MCP Runtime-configured connections External services Architecture Guide

MCP Server vs Client

Component Role Examples Location
MCP Server Provides tools demo_server.py, mcp_stdio.py backend/tools/mcp_tools/
MCP Client Connects to servers mcp_client.py, Claude Desktop backend/tools/mcp_client.py

Tool Categories

  1. Native API Tools
    • Direct Python functions (google_search, ai_search)
    • Location: backend/tools/
    • No MCP protocol involved
  2. Registered MCP Servers (mcp_* prefix)
    • Pre-configured in mcp_servers.py
    • Examples: mcp_demo, mcp_database
    • Permanent, named tools
  3. Dynamic MCP Connections (external_mcp)
    • Runtime configuration
    • Connect to any MCP server
    • Flexible, temporary connections

File Organization

Core MCP Files

  • backend/mcp_server_claude_desktop.sh - Main launcher script
  • backend/mcp_stdio.py - Claude Desktop stdio server
  • backend/mcp_stdio_compat.py - Claude Code compatibility
  • backend/mcp_tools.py - Tool registry

Infrastructure

  • backend/tools/mcp_client.py - MCP client manager
  • backend/tools/mcp_servers.py - Server registry
  • backend/tools/mcp_registry.py - Server management
  • backend/tools/mcp_tool_discovery.py - Tool discovery

Server Implementations

  • backend/tools/mcp_tools/demo_server.py - Demo server (with inline dependencies)
  • backend/tools/mcp_tools/template_server.py - Server template

Key Insights from Testing

  1. cwd parameter doesn’t work reliably in Claude Desktop configuration
  2. Use inline script dependencies (# /// script) for standalone servers
  3. Launcher scripts handle gcloud auth and environment setup
  4. Full UV path required: /Users/mark/.local/bin/uv
  5. UV syntax: uv run script.py not uv run python script.py

Common Workflows

Adding a New MCP Tool

  1. Standalone Server (Recommended): Create script with inline dependencies 
    # /// script
# dependencies = ["fastmcp>=0.1.0"]
# ///

  2. Main Server Integration: Add to backend/mcp_tools.py

  3. Registered Server: Add to backend/tools/mcp_servers.py

  4. External Service: Use external_mcp with runtime config

See Complete Guide - Adding New MCP Tools

Working Configuration (Tested ✅)

{
  "mcpServers": {
    "aitana": {
      "command": "/Users/mark/dev/aitana-labs/frontend/backend/mcp_server_claude_desktop.sh"
    },
    "aitana_demo": {
      "command": "/Users/mark/.local/bin/uv",
      "args": ["run", "/Users/mark/dev/aitana-labs/frontend/backend/tools/mcp_tools/demo_server.py"]
    }
  }
}

Testing MCP Integration

  1. Test Page: http://localhost:1956/test
  2. Direct API: /direct/tools/mcp/{server_id}/list
  3. Protocol Test: curl -X POST http://localhost:1956/mcp

See Complete Guide - Testing

Need Help?