Source Code: src/gaia/mcp/

GAIA MCP Server

Overview

The GAIA MCP Server provides an HTTP-native bridge that exposes GAIA’s AI agents to third-party applications through standard REST and JSON-RPC protocols. This enables external tools like n8n, Zapier, web applications, and custom integrations to leverage GAIA’s AI capabilities without direct Python dependencies.

When to Use MCP

Use MCP Server When

Integrating GAIA with external applications (n8n, Zapier, web apps)
Building non-Python applications that need GAIA’s AI capabilities
Creating workflow automations with tools that support HTTP/REST
Accessing GAIA from browsers or mobile applications

You DON'T Need MCP When

Using GAIA CLI directly (gaia chat, gaia llm, etc.)
Building Python applications (use GAIA’s Python API directly)
Running GAIA agents locally from the command line
Integrating with VSCode as a Language Model Provider (use the API Server instead)

Quick Start

Install GAIA

MCP is included in base installation

uv pip install -e .

Start the MCP Server

gaia mcp start

Test the Server

curl http://localhost:8765/health

Make Your First API Call

curl -X POST http://localhost:8765/chat \
  -H "Content-Type: application/json" \
  -d '{"query":"Hello GAIA"}'

Setup

Prerequisites

Install GAIA

Follow the Development Guide to install GAIA

Install the LLM backend

gaia init

Installs Lemonade Server and pulls the model. gaia daemon starts and supervises it — you don’t launch it yourself.

Verify Installation

Check server status:

gaia mcp status

Test with a simple query:

gaia mcp test --query "Hello GAIA!"

Starting the MCP Server

Foreground Mode
Background Mode
Custom Port
Verbose Logging

Start in foreground to see logs:

gaia mcp start

Start in background:

gaia mcp start --background

Start with custom port:

gaia mcp start --port 9000

Start with verbose logging (logs all HTTP requests):

gaia mcp start --verbose

Logging Behavior:

Foreground mode: Logs appear in the console
Background mode: Logs are written to gaia.mcp.log (default)
With --verbose: All HTTP requests/responses are logged (including health checks)
Main log: All MCP logs also go to gaia.log regardless of mode

Managing the Server

Check if server is running:

gaia mcp status

Test with a simple query:

gaia mcp test --query "Hello, GAIA!"

Stop the server:

gaia mcp stop

Architecture

The MCP Server acts as an HTTP bridge between external applications and GAIA’s native Python agents.

API Endpoints

REST Endpoints

Endpoint	Method	Description
`/health`	GET	Server health check
`/status`	GET	Bridge status (connected agents, loaded tools, uptime)
`/tools`	GET	List available tools
`/chat`	POST	Conversational chat (with context)
`/llm`	POST	Direct LLM queries (no context)
`/`	POST	JSON-RPC 2.0 endpoint

JSON-RPC Methods

POST / speaks MCP over JSON-RPC 2.0, so standard MCP clients (including the official SDKs) can connect to it directly.

Method	Behavior
`initialize`	Echoes the client’s `protocolVersion` if it is `2024-11-05`, `2025-03-26`, `2025-06-18`, or `2025-11-25`; otherwise answers `2025-11-25`. Advertises only `{"tools": {}}`
`notifications/*`	Accepted with HTTP `202` and an empty body (no JSON-RPC reply)
`ping`	Returns `{}`
`tools/list`	Each tool includes a JSON Schema `inputSchema`
`tools/call`	Returns `content` plus `isError`; `isError: true` means the tool ran but failed (for example, Lemonade Server is unreachable). An unknown tool name is a JSON-RPC `-32602` error

Example API Calls

Health Check
Chat (Conversational)
LLM Query (No Context)
JSON-RPC Protocol

curl http://localhost:8765/health

Response (agent/tool counts vary by installation):

{
  "status": "healthy",
  "service": "GAIA MCP Bridge (HTTP)",
  "agents": 4,
  "tools": 5
}

First message:

curl -X POST http://localhost:8765/chat \
  -H "Content-Type: application/json" \
  -d '{"query": "Hello! My name is Alice."}'

Follow-up (remembers context):

curl -X POST http://localhost:8765/chat \
  -H "Content-Type: application/json" \
  -d '{"query": "What is my name?"}'

curl -X POST http://localhost:8765/llm \
  -H "Content-Type: application/json" \
  -d '{"query": "What is artificial intelligence?"}'

curl -X POST http://localhost:8765/ \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
      "name": "gaia.chat",
      "arguments": {"query": "Hello GAIA"}
    }
  }'

Integration Examples

Python
JavaScript/Node.js
cURL

import requests
import json

def chat_with_gaia(query):
    """Chat with GAIA via MCP server (maintains context)"""
    response = requests.post(
        'http://localhost:8765/chat',
        json={'query': query}
    )
    return response.json()

Example usage:

result = chat_with_gaia("What is machine learning?")
print(result['result'])

const axios = require('axios');

async function chatWithGAIA(query) {
    const response = await axios.post(
        'http://localhost:8765/chat',
        { query: query }
    );
    return response.data;
}

Example usage:

const result = await chatWithGAIA('What is AI?');
console.log(result.result);

Chat query (maintains conversation context):

curl -X POST http://localhost:8765/chat \
  -H "Content-Type: application/json" \
  -d '{"query": "Explain neural networks"}'

Direct LLM query (no context):

curl -X POST http://localhost:8765/llm \
  -H "Content-Type: application/json" \
  -d '{"query": "What is quantum computing?"}'

n8n Integration

For detailed n8n workflow automation examples, see the n8n Integration Guide.

Quick n8n Setup

Start the MCP Server

gaia mcp start

Configure HTTP Request Node in n8n

Method: POST
URL: http://localhost:8765/chat
Body: JSON with your query

Import Example Workflow

Go to Workflows → Import
Import src/gaia/mcp/n8n.json

Available Tools

The MCP server exposes the following GAIA agents as tools:

Standard Tools (Port 8765)

Tool	Description	Example Arguments
`gaia.chat`	Conversational chat with context	`{"query": "Hello GAIA"}`
`gaia.query`	Direct LLM queries (no context); optional `model` and `max_tokens`	`{"query": "What is AI?"}`

Troubleshooting

Connection Refused

Symptoms: Cannot connect to MCP serverSolutions:

Ensure the GAIA MCP Bridge is running
Check firewall settings
Verify the correct port (default: 8765)

LLM Server Not Responding

Symptoms: Queries time out or failSolutions:

Check the daemon that supervises the model server: gaia daemon status. If none is running, gaia daemon start
If the daemon is up but the model server isn’t, read gaia daemon logs --lines 100
Check LEMONADE_BASE_URL is correct (default http://localhost:13305/api/v1)

Server Won't Start

Symptoms: Server fails to startSolutions:

Check if port 8765 is already in use: netstat -an | findstr 8765
Stop existing MCP server: gaia mcp stop
Try different port: gaia mcp start --port 8766

No Tools Available

Symptoms: Empty tools list or specific tools missingSolutions:

Check server logs: gaia mcp start --verbose
Verify GAIA installation: pip show gaia
Reinstall MCP dependencies: uv pip install -e ".[mcp]"

CLI Testing & Debugging

Use GAIA’s built-in MCP commands: Check server status:

gaia mcp status

Test with a query:

gaia mcp test --query "What is artificial intelligence?"

Start with verbose logging:

gaia mcp start --verbose

Test specific host/port:

gaia mcp test --host localhost --port 8765

Validation Scripts

GAIA provides test scripts in the tests/mcp/ directory to validate the MCP bridge. Run from the project root directory: Simple validation test:

python tests/mcp/test_mcp_simple.py

Comprehensive HTTP validation test:

python tests/mcp/test_mcp_http_validation.py

Integration tests:

python tests/mcp/test_mcp_integration.py

The tests validate:

Health checks and tool listing
Direct endpoints (/chat, /llm)
JSON-RPC protocol compliance
Error handling and CORS headers

Security Considerations

For production deployments, always implement these security measures:

Authentication: Always use authentication tokens in production
SSL/TLS: Use encrypted connections for sensitive data
Rate Limiting: Implement rate limits to prevent abuse
Access Control: Restrict access to specific IP addresses or networks
Audit Logging: Enable logging for compliance and debugging

Architecture Notes

HTTP-Native

Pure REST/JSON-RPC, no WebSocket dependencies

Stateless

Each request is independent for better scalability

Agent Access

Direct access to all GAIA agents

Loopback Browser Origins

Browser apps on localhost work; other origins need GAIA_MCP_ALLOWED_ORIGINS

VSCode Integration

GAIA MCP Server can be integrated with VSCode using MCP client capabilities. This provides an alternative integration approach to the VSCode Language Model Provider extension. For complete VSCode integration documentation, see VSCode Integration Documentation. Quick Setup:

Start MCP Server

gaia mcp start

Configure VSCode MCP Client

Configure MCP client in VSCode to connect to http://localhost:8765

Access GAIA Tools

Access GAIA tools via MCP client

VSCode Integration

VSCode extension and MCP integration

GAIA API Server

OpenAI-compatible API for VSCode extension

n8n Integration

Detailed workflow automation examples

GAIA CLI

Command line interface reference

Development Guide - Setup and contribution guidelines

Integrations

Packaging & Distribution

MCP Server

GAIA MCP Server

Overview

When to Use MCP

Use MCP Server When

You DON'T Need MCP When

Quick Start

Setup

Prerequisites

Verify Installation

Starting the MCP Server

Managing the Server

Architecture

API Endpoints

REST Endpoints

JSON-RPC Methods

Example API Calls

Integration Examples

n8n Integration

Quick n8n Setup

Available Tools

Standard Tools (Port 8765)

Troubleshooting

CLI Testing & Debugging

Validation Scripts

Security Considerations

Architecture Notes

HTTP-Native

Stateless

Agent Access

Loopback Browser Origins

VSCode Integration

See Also

VSCode Integration

GAIA API Server

n8n Integration

GAIA CLI

​GAIA MCP Server

​Overview

​When to Use MCP

Use MCP Server When

You DON'T Need MCP When

​Quick Start

​Setup

​Prerequisites

​Verify Installation

​Starting the MCP Server

​Managing the Server

​Architecture

​API Endpoints

​REST Endpoints

​JSON-RPC Methods

​Example API Calls

​Integration Examples

​n8n Integration

​Quick n8n Setup

​Available Tools

​Standard Tools (Port 8765)

​Troubleshooting

​CLI Testing & Debugging

​Validation Scripts

​Security Considerations

​Architecture Notes

HTTP-Native

Stateless

Agent Access

Loopback Browser Origins

​VSCode Integration

​See Also

VSCode Integration

GAIA API Server

n8n Integration

GAIA CLI

GAIA MCP Server

Overview

When to Use MCP

Quick Start

Setup

Prerequisites

Verify Installation

Starting the MCP Server

Managing the Server

Architecture

API Endpoints

REST Endpoints

JSON-RPC Methods

Example API Calls

Integration Examples

n8n Integration

Quick n8n Setup

Available Tools

Standard Tools (Port 8765)

Troubleshooting

CLI Testing & Debugging

Validation Scripts

Security Considerations

Architecture Notes

VSCode Integration

See Also