MCP Client

Connect your GAIA agent to any tool ecosystem with a single line of code.

🔌 Universal tool integration - Filesystem, GitHub, databases, and hundreds more
⚡ Zero code required - Configure once, tools auto-register
🌍 Industry standard - Built on Model Context Protocol
🔍 Auto-discovery - Tools document themselves to your agent

Examples:

examples/mcp_time_server_agent.py - Simple Python server example
examples/mcp_config_based_agent.py - Config file-based loading
examples/mcp_windows_system_health_agent.py - System analysis with Windows-MCP

See Also:

SDK Reference - Quick code snippets
Full Specification - Complete API documentation and implementation details

What is MCP?

The Problem

Building AI agents that interact with external tools is hard. Every service has its own API, authentication method, and data format. Want your agent to read files, create GitHub issues, AND query a database? That’s three separate integrations to build and maintain.

The Solution

MCP (Model Context Protocol) is like USB for AI - a universal connector that lets any AI application talk to any tool. Just as USB eliminated the need for custom cables, MCP eliminates the need for custom integrations.

Before MCP:  Agent → Custom Code → GitHub API
             Agent → Custom Code → Filesystem API
             Agent → Custom Code → Database API

With MCP:    Agent → MCP → Any Tool

Learn More: MCP is an open standard created by Anthropic. Visit modelcontextprotocol.io for the full specification and ecosystem.

How GAIA Uses MCP

GAIA agents act as MCP clients that connect to MCP servers. Each server exposes tools (like “read_file” or “create_issue”) that your agent can call. The protocol handles all the communication details - you just connect and use the tools.

See It In Action

Try it now - this connects to an MCP server and starts an interactive session:

uv run examples/mcp_config_based_agent.py

Connected to MCP servers: time
Try: 'What time is it in Tokyo?' | Type 'quit' to exit.

You: What time is it in Tokyo?

Agent: The current time in Tokyo is 11:59 PM on Wednesday, January 28, 2026, Japan Standard Time (JST).

MCP server connected, tools auto-discovered, and the agent uses them naturally.

Quick Start

Initialize MCP configuration

gaia init --profile mcp

This creates ~/.gaia/mcp_servers.json with an empty configuration.

Add an MCP server

Add the official MCP Time Server:

gaia mcp add time "uvx mcp-server-time"

Or edit ~/.gaia/mcp_servers.json directly:

{
  "mcpServers": {
    "time": {
      "command": "uvx",
      "args": ["mcp-server-time"]
    }
  }
}

Use in your agent

from gaia.agents.base import Agent
from gaia.mcp import MCPClientMixin

class MCPAgent(Agent, MCPClientMixin):
    """Agent with MCP server support."""

    def __init__(self, **kwargs):
        Agent.__init__(self, **kwargs)
        MCPClientMixin.__init__(self)  # Config auto-loaded!

    def _get_system_prompt(self) -> str:
        return "You are a helpful assistant with access to MCP tools."

    def _register_tools(self) -> None:
        pass  # MCP tools are auto-registered by the mixin

agent = MCPAgent()
result = agent.process_query("What time is it in Tokyo?")
print(result.get("result", "No response"))

Expected output:

The current time in Tokyo is 11:42 PM on Wednesday, January 28, 2026 (JST, UTC+9).

Verify with a query

Run the config-based example to interactively test:

uv run examples/mcp_config_based_agent.py

Connected to MCP servers: time
Try: 'What time is it in Tokyo?' | Type 'quit' to exit.

You: What time is it in Paris?
Agent: The current time in Paris is 3:42 PM on Wednesday, January 28, 2026 (CET, UTC+1).

You: And in New York?
Agent: The current time in New York is 9:42 AM on Wednesday, January 28, 2026 (EST, UTC-5).

How It Works

Your Agent inherits from Agent + MCPClientMixin — the mixin adds MCP capabilities
MCPClientManager handles connections to multiple servers
Transport Layer communicates via stdio (subprocess)
MCP Servers expose tools that become available to your agent

Connecting to Servers

`connect_mcp_server(name, config)`

Parameter	Type	Required	Description
`name`	`str`	Yes	Friendly name for the server (used as tool prefix)
`config`	`dict`	Yes	Server configuration (see fields below)
`config.command`	`str`	Yes	Base command to run (e.g., `"npx"`, `"uvx"`)
`config.args`	`list[str]`	No	Arguments for the command
`config.env`	`dict[str, str]`	No	Environment variables for the server process

Returns: bool — True if connection and tool registration succeeded.

Finding MCP servers: Browse the MCP Server Hub on glama.ai to discover servers and their available tools. Each listing shows the install command, available tools, and usage examples.

From Config File
Programmatically
Via CLI

# Load all servers from mcp_servers.json
count = agent.load_mcp_servers_from_config()
print(f"Loaded {count} servers")

# Connect to individual servers in code
agent.connect_mcp_server("filesystem", {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
})

# Add server to config
gaia mcp add filesystem "npx -y @modelcontextprotocol/server-filesystem /tmp"

# List configured servers
gaia mcp list

After connecting, verify the server is working by sending a query:

result = agent.process_query("List the files in /tmp")
print(result.get("result"))

Configuration

Config File Locations

GAIA looks for mcp_servers.json in two locations (in order):

Project directory - ./mcp_servers.json in current working directory
Global config - ~/.gaia/mcp_servers.json in user’s home directory

This allows project-specific MCP server configurations while maintaining a global default.

Config File Format

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/documents"]
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxx"
      }
    }
  }
}

This format is compatible with Claude Desktop and other Anthropic tools. The mcpServers key, separate command/args fields, and env support are standard across the ecosystem.

Popular MCP Servers

Filesystem
GitHub
Python Servers

agent.connect_mcp_server("filesystem", {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/directory"]
})

agent.connect_mcp_server("github", {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": {"GITHUB_TOKEN": "ghp_your_token_here"}
})

# Python-based MCP servers (via uvx)
agent.connect_mcp_server("time", {
    "command": "uvx",
    "args": ["mcp-server-time"]
})

Adding a New MCP Server

Find a server

Browse the MCP Server Hub on glama.ai or the official MCP servers list. Each listing includes the install command and available tools.

Add to config

gaia mcp add <name> "<command>"

For example, to add the Memory server:

gaia mcp add memory "npx -y @modelcontextprotocol/server-memory"

Test the connection

gaia mcp test-client memory

This verifies GAIA can start the server and discover its tools.

Verify with a query

uv run examples/mcp_config_based_agent.py

Connected to MCP servers: memory, time
Try: 'What time is it in Tokyo?' | Type 'quit' to exit.

You: Remember that my favorite color is blue
Agent: I've stored that your favorite color is blue.

Security Considerations

Vet MCP servers before connecting. Each MCP server runs as a subprocess with access to your system. A malicious server could read files, execute commands, or exfiltrate data.

Before adding an MCP server:

Review the source — Only use servers from trusted sources with public repositories
Check permissions — Understand what system access the server requires (filesystem paths, API tokens, network access)
Limit scope — When connecting filesystem servers, restrict to specific directories rather than /
Audit environment variables — Never pass secrets (API keys, tokens) to servers you haven’t reviewed

Complete Examples

Working examples are available in the GAIA repository:

Time Server Agent

Simple example connecting to a Python MCP server via uvx

Config-Based Agent

Load servers from mcp_servers.json - recommended for production

For detailed API usage and patterns, see the SDK Reference.

Under the Hood

CLI Commands

GAIA provides CLI commands for managing MCP server configurations without writing code.

MCP CLI Reference

Complete documentation of all MCP CLI commands: add, list, tools, test-client, remove

Quick reference:

gaia mcp add <name> "<command>"     # Add server to config
gaia mcp list                        # List configured servers
gaia mcp tools <name>                # List tools from server
gaia mcp test-client <name>          # Test connection
gaia mcp remove <name>               # Remove server

For detailed usage, parameters, and output examples, see the CLI Reference.

Best Practices

Error Handling

Always handle connection failures gracefully:

success = agent.connect_mcp_server("server", {
    "command": "npx",
    "args": ["-y", "@mcp/server"]
})
if not success:
    print("Failed to connect, using fallback tools")

Resource Cleanup

Disconnect servers when done:

def __del__(self):
    for server in self.list_mcp_servers():
        self.disconnect_mcp_server(server)

Tool Discovery

Cache tool lists instead of fetching repeatedly:

tools = client.list_tools()  # Cached by default
tools = client.list_tools(refresh=True)  # Force refresh

Debug Mode

Enable debug logging during development:

client = MCPClient.from_config(
    "server",
    {"command": "npx", "args": ["-y", "@mcp/server"]},
    debug=True  # Shows detailed logs
)

Prerequisites

GAIA Installation

Initialize MCP configuration:

gaia init --profile mcp

For development with MCP extras:

uv pip install -e ".[mcp,dev]"

Node.js (Optional)

Required only for npm-based MCP servers, e.g.:

npx -y @modelcontextprotocol/server-memory

See Setup Guide for NVM installation instructions.

Troubleshooting

Connection fails with 'command not found'

Problem: The MCP server command (like npx or uvx) isn’t in your PATH.Solution:

# Check if npx is available
which npx

# If not, install Node.js or ensure it's in your PATH
# On macOS with nvm:
source ~/.nvm/nvm.sh

Config file not found

Problem: load_mcp_servers_from_config() returns 0 servers.Solution: GAIA looks for mcp_servers.json in:

Current working directory (./mcp_servers.json)
Home directory (~/.gaia/mcp_servers.json)

Verify the file exists and contains valid JSON:

cat ./mcp_servers.json
# or
cat ~/.gaia/mcp_servers.json

Tools not appearing in agent

Problem: Connected to server but tools aren’t being used.Solution:

Verify connection succeeded:

print(agent.list_mcp_servers())  # Should show server name

List available tools:
```
gaia mcp tools <server-name>
```

Enable debug mode to see tool registration:

import logging
logging.basicConfig(level=logging.DEBUG)

Server process hangs or times out

Problem: Connection hangs during startup.Solution:

Some servers need initialization time. Try increasing timeout:
```
agent.connect_mcp_server("server", config, timeout=30)
```
Test the server directly:
```
gaia mcp test-client <server-name>
```

Next Steps

MCP Server Hub

Browse and discover MCP servers with install commands and tool listings

Official MCP Servers

Browse official MCP servers from Anthropic

Build a Custom Agent

Learn how to create agents that leverage MCP tools

Create MCP Server

Build your own MCP server to expose custom tools

API Reference

Detailed API documentation for MCP Client

Getting Started

User Guides

Playbooks

SDK Reference

What is MCP?

The Problem

The Solution

How GAIA Uses MCP

See It In Action

Quick Start

How It Works

Connecting to Servers

`connect_mcp_server(name, config)`

Configuration

Config File Locations

Config File Format

Popular MCP Servers

Adding a New MCP Server

Security Considerations

Complete Examples

Time Server Agent

Config-Based Agent

Under the Hood

MCP CLI Reference

Error Handling

Resource Cleanup

Tool Discovery

Debug Mode

GAIA Installation

Node.js (Optional)

Troubleshooting

Next Steps

MCP Server Hub

Official MCP Servers

Build a Custom Agent

Create MCP Server

API Reference

Getting Started

User Guides

Playbooks

SDK Reference

​What is MCP?

​The Problem

​The Solution

​How GAIA Uses MCP

​See It In Action

​Quick Start

​How It Works

​Connecting to Servers

​connect_mcp_server(name, config)

​Configuration

​Config File Locations

​Config File Format

​Popular MCP Servers

​Adding a New MCP Server

​Security Considerations

​Complete Examples

Time Server Agent

Config-Based Agent

​Under the Hood

MCP CLI Reference

Error Handling

Resource Cleanup

Tool Discovery

Debug Mode

GAIA Installation

Node.js (Optional)

​Troubleshooting

​Next Steps

MCP Server Hub

Official MCP Servers

Build a Custom Agent

Create MCP Server

API Reference

What is MCP?

The Problem

The Solution

How GAIA Uses MCP

See It In Action

Quick Start

How It Works

Connecting to Servers

`connect_mcp_server(name, config)`

Configuration

Config File Locations

Config File Format

Popular MCP Servers

Adding a New MCP Server

Security Considerations

Complete Examples

Under the Hood

Troubleshooting

Next Steps