MCP Server

HTTP-native bridge exposing GAIA AI agents through REST and JSON-RPC protocols

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 jira, 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

1. Install GAIA

   MCP is included in base installation

   uv pip install -e .
   
2. Start the MCP Server

   gaia mcp start
   
3. Test the Server

   curl http://localhost:8765/health
   
4. Make Your First API Call

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

Setup

Prerequisites

1. Install GAIA

   Follow the Development Guide to install GAIA

2. Start Lemonade Server

   Ensure the LLM backend is running:

   lemonade-server serve --ctx-size 8192
   
3. Install Docker (for Docker agent)

   Install Docker Engine or Desktop from docker.com

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

Start in foreground to see logs:

gaia mcp start

Background Mode

Start in background:

gaia mcp start --background

Custom Port

Start with custom port:

gaia mcp start --port 9000

Verbose Logging

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
/tools	GET	List available tools
/chat	POST	Conversational chat (with context)
/llm	POST	Direct LLM queries (no context)
/jira	POST	Jira operations
/	POST	JSON-RPC 2.0 endpoint

Docker uses a newer framework using FastMCP-powered server. See examples in Docker section below.

Example API Calls

Health Check

curl http://localhost:8765/health

Response:

{
  "status": "healthy",
  "agents": 4,
  "tools": 8
}

Chat (Conversational)

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?"}'

LLM Query (No Context)

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

Jira Operations

curl -X POST http://localhost:8765/jira \
  -H "Content-Type: application/json" \
  -d '{"query": "show my open issues"}'

Docker Operations

Start Docker MCP server:

gaia mcp docker --port 8080

Containerize application via JSON-RPC:

curl -X POST http://localhost:8080/ \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
      "name": "dockerize",
      "arguments": {
        "appPath": "/absolute/path/to/app",
        "port": 5000
      }
    }
  }'

JSON-RPC Protocol

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

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'])

JavaScript/Node.js

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);

cURL

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?"}'

Jira operations:

curl -X POST http://localhost:8765/jira \
  -H "Content-Type: application/json" \
  -d '{"query": "create idea: Add dark mode feature"}'

n8n Integration

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

Quick n8n Setup

1. Start the MCP Server

   gaia mcp start
   
2. Configure HTTP Request Node in n8n

   • Method: POST
   • URL: http://localhost:8765/chat
   • Body: JSON with your query
3. 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)	{"query": "What is AI?"}
gaia.jira	Natural language Jira operations	{"query": "show my issues"}
gaia.blender.create	3D content creation	{"command": "create_cube", "parameters": {}}

Docker Tool (FastMCP framework on port 8080)

Tool	Description	Example Arguments
dockerize	Containerize application (analyze → create Dockerfile → build → run)	{"appPath": "/absolute/path/to/app", "port": 5000}

To use the Docker tool, start the Docker MCP server: gaia mcp docker --port 8080

The Docker agent is GAIA’s first to use the new FastMCP framework. See Docker Agent Documentation.

Troubleshooting

Connection Refused

Symptoms: Cannot connect to MCP server

Solutions:

• 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 fail

Solutions:

• Start the Lemonade server: lemonade-server serve
• Check GAIA_BASE_URL is correct
• Verify models are loaded

Server Won't Start

Symptoms: Server fails to start

Solutions:

• 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 missing

Solutions:

• 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

Jira-specific MCP tests:

python tests/mcp/test_mcp_jira.py

Docker-specific MCP tests:

python tests/mcp/test_mcp_docker.py

Integration tests:

python tests/mcp/test_mcp_integration.py

The tests validate:

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

Security Considerations

For production deployments, always implement these security measures:

1. Authentication: Always use authentication tokens in production
2. SSL/TLS: Use encrypted connections for sensitive data
3. Rate Limiting: Implement rate limits to prevent abuse
4. Access Control: Restrict access to specific IP addresses or networks
5. 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

CORS Enabled

Works with browser-based applications

Applications

GAIA provides applications that connect to the MCP server. For using existing apps or building new ones, see the Apps Documentation.

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:

1. Start MCP Server

   gaia mcp start
   
2. Configure VSCode MCP Client

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

3. Access GAIA Tools

   Access GAIA tools via MCP client

See Also

VSCode Integration

VSCode extension and MCP integration

GAIA API Server

OpenAI-compatible API for VSCode extension

n8n Integration

Detailed workflow automation examples

Jira Agent

Natural language Jira operations

Docker Agent

Natural language Docker containerization

GAIA CLI

Command line interface reference

• Development Guide - Setup and contribution guidelines

---