Source Code: src/gaia/mcp/ (n8n uses the MCP Server)

GAIA n8n Integration Guide

This guide explains how to integrate GAIA’s AI capabilities into n8n workflows using the GAIA MCP Server.

Overview

n8n can leverage GAIA’s AI agents (LLM, Chat) through HTTP requests to the MCP server. This enables powerful AI-driven workflow automation without writing code.

Architecture

How It Works

External Services

Email, Calendar, Slack, etc. trigger workflows or receive results

n8n Workflows

Orchestrates the flow between services and GAIA

GAIA MCP Server

HTTP bridge that exposes GAIA agents as REST endpoints

GAIA Agents

Specialized AI agents for different tasks (Chat, LLM)

LLM Backend

Lemonade server provides the AI model execution

AI Text Processing

AI-powered text processing and summarization

Conversational Chat

Conversational chat with context

Prerequisites

1. Set up GAIA MCP Server

Follow the MCP Server Documentation to:

Install GAIA with MCP support
Start the Lemonade LLM server
Start the MCP bridge server
Verify it’s running with gaia mcp status

2. Install and Run n8n Locally

Using npx (No Installation)
Global Installation

npx n8n

npm install -g n8n
n8n start

n8n will open automatically at http://localhost:5678

Throughout this guide, use http://localhost:8765 for MCP server connections.

Getting Started: Step-by-Step

Step 1: Verify MCP Server is Running

Before creating workflows, verify the MCP server is accessible:

# Check server status
gaia mcp status

# Test with curl
curl http://localhost:8765/health

Step 2: Create Your First n8n Workflow

Open n8n

Navigate to http://localhost:5678

Create New Workflow

Click “New Workflow”

Follow Examples

Start with simple GET requests and progress to more complex use cases

Available Endpoints

The MCP bridge provides the following HTTP endpoints:

Health Check

GET /health - Basic health check
Returns: {"status": "healthy", "service": "GAIA MCP Bridge (HTTP)", "agents": 4, "tools": 5}

Status (Detailed)

GET /status - Comprehensive status with all agents, tools, and endpoints
Returns: Detailed JSON with agents, tools, capabilities, and available endpoints

Tool Listing

GET /tools - List all available GAIA tools
Returns: Array of tool definitions with names, descriptions, and input schemas

Direct Agent Endpoints

LLM Queries
Chat Interface

POST /llm - Direct LLM queries (no conversation context)

{
  "query": "What is artificial intelligence?"
}

POST /chat - Interactive chat with conversation context

{
  "query": "Continue our discussion about AI"
}

JSON-RPC Endpoint

POST / - Standard JSON-RPC 2.0 interface for MCP protocol Supports methods:

initialize - Initialize MCP connection
tools/list - List available tools
tools/call - Execute a specific tool. Check result.isError: it is true when the tool ran but failed

See the MCP integration guide for the full method list.

Integration Examples: From Simple to Complex

Example 1: Simple Health Check (GET Request)

Add HTTP Request Node

Add an HTTP Request node to your workflow

Configure Node

Method: GET
URL: http://localhost:8765/health

Execute

Click “Execute Node”

Expected response:

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

Purpose: Verify n8n can connect to the MCP server

Example 2: Get Detailed Status (GET Request)

Add HTTP Request Node

Add an HTTP Request node

Configure

Method: GET
URL: http://localhost:8765/status

Execute

Execute to see all available agents, tools, and endpoints

Purpose: See all available agents and tools

Example 3: Simple Chat (POST Request)

Add HTTP Request Node

Add an HTTP Request node

Configure

Method: POST
URL: http://localhost:8765/chat
Body Content Type: JSON
JSON Body:

{
  "query": "Hello GAIA! What can you help me with today?"
}

Execute

Execute to get an AI response

Purpose: Send a basic message to the AI

Example 4: LLM Analysis (POST Request)

Add HTTP Request Node

Add an HTTP Request node

Configure

Method: POST
URL: http://localhost:8765/llm
Body Content Type: JSON
JSON Body:

{
  "query": "Summarize the following text: [your text here]"
}

Purpose: Analyze or process text with AI

Building Complete Workflows

Workflow 1: Daily Standup Assistant

Components: Manual Trigger → Source HTTP Request → LLM Summarize → Output

Add Manual Trigger

Add Manual Trigger node (or Schedule Trigger for automation)

Add Source HTTP Request

HTTP Request node pulling yesterday’s activity from wherever you track it — a calendar, an issue tracker’s own REST API, a Slack channel export

Add LLM HTTP Request

HTTP Request node for LLM:

{
  "query": "Format this as a standup update: {{$json.result}}"
}

Add Output Node

Send to Slack/Email node with formatted output

Workflow 2: Smart Issue Triage

Components: Webhook Trigger → LLM Analysis → Issue Tracker Update

Add Webhook Node

Webhook node to receive new issue notifications

Add LLM Analysis

HTTP Request to LLM for analysis:

{
  "query": "Analyze this issue and suggest priority and assignee: {{$json.description}}"
}

Update Issue Tracker

HTTP Request to your issue tracker’s own API to apply the AI suggestions — GAIA only supplies the LLM analysis step, the tracker update goes directly to that service, not through GAIA

Import Pre-built Workflow

Navigate to Import

In n8n, go to Workflows → Import from File

Select File

Select src/gaia/mcp/n8n.json

Review Workflow

The workflow includes examples of all endpoints

Tips for Building Workflows

Using Variables in Requests

n8n allows you to reference data from previous nodes:

{
  "query": "Summarize this: {{$node['Previous Node'].json.content}}"
}

Error Handling

Always add an IF node after HTTP requests to handle errors:

Check if {{$json.success}} is true
Route errors to notification or retry logic

Rate Limiting

For bulk operations, add a Wait node between requests:

Wait 1-2 seconds between API calls
Prevents overwhelming the MCP server

Testing Workflows

Use Manual Trigger

Use Manual Trigger during development

Test Individually

Test each node individually with “Execute Node”

Pin Data

Use “Pin Data” to save test responses

Switch to Production

Switch to production triggers when ready

Understanding Responses

Successful Responses

Each endpoint returns different data structures:

GET Endpoints
POST Endpoints

health, status, tools:

Return status information directly
No success field needed

chat, llm:

Always include success: true/false
Main content in result field
Additional info in metadata (optional)

Handling Errors

// In n8n expressions:
{{$json.success ? $json.result : 'Error: ' + $json.error}}

Best Practices

Start Simple

Begin with GET requests, then move to POST

Use localhost

Use localhost for local server connections

Test Incrementally

Test each node before building complex workflows

Handle Errors

Add IF nodes to check success field

Set Timeouts

Use 30s timeout for LLM operations

Log Responses

Use Set nodes to capture responses for debugging

Troubleshooting

MCP Bridge Not Accessible / "Service refused the connection"

If you get “The service refused the connection - perhaps it is offline” or ECONNREFUSED ::1:8765 error:QUICK FIX: Ensure the MCP server is running with gaia mcp start and use http://localhost:8765 for connections.For detailed MCP server troubleshooting (ports, processes, Docker/WSL), see the MCP Server Documentation.

n8n-Specific Connection Issues

When MCP works locally but n8n doesn’t:Connection refused issue (Most Common):

Error: connect ECONNREFUSED ::1:8765 means the MCP server may not be running
FIX: Ensure MCP server is running with gaia mcp start and use http://localhost:8765
If issues persist, check firewall settings or try http://127.0.0.1:8765 as an alternative

If n8n is in browser (n8n.cloud or self-hosted web):

Browser security blocks ALL localhost connections from web apps. This is a browser security feature (CORS/Mixed Content) that cannot be bypassed.

Solutions:a) Run n8n locally (BEST OPTION):

# Install and run n8n on your machine
npm install -g n8n
n8n start
# Opens at http://localhost:5678
# Now it can access your local MCP bridge

b) Use ngrok tunnel (EASIEST for testing with n8n.cloud):

# Install ngrok (or download from ngrok.com)
npm install -g ngrok

# In Terminal 1: Start your MCP bridge
gaia mcp start

# In Terminal 2: Create tunnel to expose MCP
ngrok http 8765

# You'll get a URL like: https://abc123.ngrok.io
# Use this URL in n8n.cloud instead of localhost
# Example: https://abc123.ngrok.io/health

c) Use localtunnel (Alternative to ngrok):

# Install localtunnel
npm install -g localtunnel

# Expose your MCP bridge
lt --port 8765
# Gives URL like: https://xyz.loca.lt
# Use this in n8n.cloud

d) Deploy MCP to cloud (for production):

Deploy GAIA MCP to AWS/Azure/Heroku
Use the public URL in n8n.cloud

To find your computer’s IP (for network access):

# Windows
ipconfig | findstr IPv4

# Then use: http://[your-IP]:8765/health
# Example: http://192.168.1.100:8765/health

Test the correct URL first:

# From where n8n is running, test:
curl http://localhost:8765/health  # localhost
curl http://192.168.1.100:8765/health  # Using your machine's IP

LLM Queries Slow

Solutions:

Ensure Lemonade server is running
Check if model is loaded in memory
Consider using smaller models for faster responses

n8n Connection Issues

Solutions:

First try: Ensure MCP server is running and use http://localhost:8765
Verify n8n can reach the MCP bridge
Browser-based n8n on another origin is refused (403) by the bridge; add that origin to GAIA_MCP_ALLOWED_ORIGINS (comma-separated) before gaia mcp start
Test with curl first to isolate issues

Advanced Configuration

For custom ports and other advanced MCP server configuration options, see the MCP Server Documentation.

Security Considerations

For production deployments, always implement these security measures:

Authentication

Add API key authentication

HTTPS

Use reverse proxy with SSL

Rate Limiting

Implement rate limiting

Input Validation

Validate all input parameters

Network Isolation

Run in isolated network segment

Example Production Setup

Using nginx reverse proxy:

server {
    listen 443 ssl;
    server_name gaia-mcp.example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:8765;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;

        # API Key validation
        if ($http_x_api_key != "your-secret-key") {
            return 403;
        }
    }
}

Support

Documentation: See other GAIA docs in /docs
Issues: Report issues on GitHub
Examples: Check /examples folder for more workflows

Next Steps

Set up MCP Server

Follow the MCP Documentation

Import Example Workflow

Import the example workflow from src/gaia/mcp/n8n.json

Build Custom Workflows

Build custom workflows using the endpoints documented above

Share Workflows

Share your workflows with the community

​GAIA n8n Integration Guide

​Overview

​Architecture

​How It Works

AI Text Processing

Conversational Chat

​Prerequisites

​1. Set up GAIA MCP Server

​2. Install and Run n8n Locally

​Getting Started: Step-by-Step

​Step 1: Verify MCP Server is Running

​Step 2: Create Your First n8n Workflow

​Available Endpoints

​Health Check

​Status (Detailed)

​Tool Listing

​Direct Agent Endpoints

​JSON-RPC Endpoint

​Integration Examples: From Simple to Complex

​Example 1: Simple Health Check (GET Request)

​Example 2: Get Detailed Status (GET Request)

​Example 3: Simple Chat (POST Request)

​Example 4: LLM Analysis (POST Request)

​Building Complete Workflows

​Workflow 1: Daily Standup Assistant

​Workflow 2: Smart Issue Triage

​Import Pre-built Workflow

​Tips for Building Workflows

​Using Variables in Requests

​Error Handling

​Rate Limiting

​Testing Workflows

​Understanding Responses

​Successful Responses

​Handling Errors

​Best Practices

Start Simple

Use localhost

Test Incrementally

Handle Errors

Set Timeouts

Log Responses

​Troubleshooting

​Advanced Configuration

​Security Considerations

​Example Production Setup

​Support

​Next Steps

GAIA n8n Integration Guide

Overview

Architecture

How It Works

Prerequisites

1. Set up GAIA MCP Server

2. Install and Run n8n Locally

Getting Started: Step-by-Step

Step 1: Verify MCP Server is Running

Step 2: Create Your First n8n Workflow

Available Endpoints

Health Check

Status (Detailed)

Tool Listing

Direct Agent Endpoints

JSON-RPC Endpoint

Integration Examples: From Simple to Complex

Example 1: Simple Health Check (GET Request)

Example 2: Get Detailed Status (GET Request)

Example 3: Simple Chat (POST Request)

Example 4: LLM Analysis (POST Request)

Building Complete Workflows

Workflow 1: Daily Standup Assistant

Workflow 2: Smart Issue Triage

Import Pre-built Workflow

Tips for Building Workflows

Using Variables in Requests

Error Handling

Rate Limiting

Testing Workflows

Understanding Responses

Successful Responses

Handling Errors

Best Practices

Troubleshooting

Advanced Configuration

Security Considerations

Example Production Setup

Support

Next Steps