Skip to content

MCP Server Integration

Model Context Protocol (MCP) lets AI assistants call external tools safely and consistently. For Gaia builders, MCP is a strong pattern when you want Cursor, Claude Desktop, or other MCP clients to query enterprise data through your server.

Why Use MCP With Gaia

  • Standard tool schema for AI clients
  • Cleaner separation between AI client and enterprise API details
  • Centralized auth, logging, and policy checks in your server
  • Reusable tool surface across multiple MCP-capable clients

Reference Example in This Project

Use the included example:

  • examples/04-gaia-mcp-server

It exposes Gaia operations as MCP tools over Streamable HTTP:

  • list_datasets
  • ask
  • exhaustive_search

The MCP endpoint is mounted at:

Text Only
http://localhost:8002/mcp

Minimal Server Pattern

Python
from fastapi import FastAPI
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("Gaia MCP", json_response=True, streamable_http_path="/", host="0.0.0.0")

@mcp.tool()
def list_datasets() -> dict:
    ...

app = FastAPI()
app.mount("/mcp", mcp.streamable_http_app())

Authentication Pattern

For enterprise deployments, avoid passing Gaia keys from the MCP client. Prefer:

  1. MCP server holds the Gaia credential server-side
  2. Client authenticates to your MCP server (session/token/OAuth)
  3. MCP server applies tenant/user policy and forwards only allowed requests

Do not hard-code API keys

Keep GAIA_API_KEY in environment variables, Key Vault, or another secret manager. Never commit secrets to source control.

Client Testing Workflow

MCP Inspector

Bash
npx -y @modelcontextprotocol/inspector
  • Transport: Streamable HTTP
  • URL: http://localhost:8002/mcp

Cursor MCP config

JSON
{
  "mcpServers": {
    "gaia-example": {
      "transport": {
        "type": "streamable-http",
        "url": "http://localhost:8002/mcp"
      }
    }
  }
}

Production Checklist for Gaia MCP

  • Add per-user auth (OAuth/JWT/session)
  • Add rate limiting and request tracing
  • Add audit logs for tool calls
  • Add policy checks before calling Gaia
  • Run in a container and deploy behind HTTPS
  • Add health endpoint and monitoring

Next Steps