MCP Quick Reference

For Complete Documentation:

Quick Setup for Claude Desktop & Claude Code

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"]
    }
  }
}

Share with Claude Code

claude mcp add-from-claude-desktop

Start HTTP Server (Alternative)

cd /Users/mark/dev/aitana-labs/frontend/backend
uv run app_fastapi.py
# Or for HTTPS:
uv run app_https.py

Test Page

Open browser: http://localhost:1956/test

Quick Tests

Check MCP Status

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

List All Tools

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

Test Demo 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 World!"}
    }
  }' | jq

Add New Tool

Method 1: Standalone MCP Server with Inline Dependencies

#!/usr/bin/env python3
# /// script
# requires-python = ">=3.10"
# dependencies = [
#     "fastmcp>=0.1.0",
# ]
# ///

from fastmcp import FastMCP

mcp = FastMCP(name="My Tools")

@mcp.tool()
def my_tool(text: str) -> str:
    """Tool description"""
    return f"Result: {text}"

if __name__ == "__main__":
    mcp.run()

Add to Claude Desktop:

{
  "mcpServers": {
    "my-tools": {
      "command": "/Users/mark/.local/bin/uv",
      "args": ["run", "/path/to/my_tools.py"]
    }
  }
}

Method 2: Add to Main MCP Server

Edit backend/mcp_tools.py - See Complete Guide

Key Endpoints

Endpoint Description
/test Interactive test dashboard
/mcp Main MCP server
/aitana-mcp Aitana tools MCP
/mcp/debug MCP status info
/health/detailed System health
/vac/assistant/{id} Assistant API
/vac/assistants List assistants

Key Files

Launcher Scripts

  • backend/mcp_server_claude_desktop.sh - Main launcher with gcloud auth
  • backend/mcp_server_claude_code.sh - Claude Code launcher (uses compat)

Core MCP Files

  • backend/mcp_stdio.py - Claude Desktop stdio server
  • backend/mcp_stdio_compat.py - Claude Code compatibility wrapper
  • backend/mcp_tools.py - Aitana MCP tools registry

Example Servers

  • backend/tools/mcp_tools/demo_server.py - Demo with inline dependencies
  • backend/tools/mcp_tools/template_server.py - Template for new servers

New Features

✅ create_app_with_mcp() - One-line setup
✅ @vac_routes.add_mcp_tool - Dynamic tools
✅ /test - Interactive dashboard
✅ SSE endpoints - Auto-created
✅ Dual MCP servers - Main + Aitana