Skip to content

MCP Server

Jump to bottom
mbtiongson1 edited this page Jun 22, 2026 · 3 revisions

MCP Server

The Gaia MCP server connects the skill registry directly to AI coding tools — Claude Code, Cursor, VS Code, and any other MCP-compatible agent. Once connected, your agent can look up skills, get fusion recommendations, and propose new skills without leaving the editor.

Quick Install

You can install the Gaia MCP server directly into your AI clients:

Agent Install Command / Configuration
Claude Code claude mcp add gaia -- npx -y @gaia-registry/mcp-server
Any MCP client Command: npx, args: -y, @gaia-registry/mcp-server

Note

The server automatically reads the user config at ~/.gaia/config.json. Ensure you have run gaia dev init or configured gaiaUser in your environment (GAIA_USER). Optionally set GITHUB_TOKEN to enable pull request tool capabilities.

Manual Config

Add the server config block to your IDE/client MCP configuration (e.g. ~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "gaia": {
      "command": "npx",
      "args": ["-y", "@gaia-registry/mcp-server"],
      "env": {
        "GAIA_USER": "your-github-username",
        "GITHUB_TOKEN": "your-github-token"
      }
    }
  }
}

Build from source

If you want to build and run the MCP server locally from the repository source code:

# Navigate to the mcp package directory
cd packages/mcp

# Install dependencies and build TypeScript
npm install
npm run build

# Start the server (runs via stdio)
node dist/bin/gaia-mcp.js

You can also run or manage the built server using the Python CLI:

  • Stdio Mode: 
    gaia dev mcp
  • Daemon Mode (runs in the background): 
    # Start the background daemon
gaia dev mcp start

# Check daemon status
gaia dev mcp status

# Stop the background daemon
gaia dev mcp stop

Available Tools

The MCP server exposes the following tools to the connected LLM / AI agent:

Tool Name Parameters Description
gaia_lookup query (string) Search skills by ID or fuzzy name. Returns skill metadata, prerequisites, derivatives, evidence, and graph location.
gaia_my_tree username (string, optional) View the configured user's skill tree, showing unlocked skills, pending fusions, and level stats.
gaia_suggest context (array, optional), tools (array, optional) Request fusion suggestions. Returns skills/fusions that are adjacent to your demonstrated skills.
gaia_scan_context connectedTools (array), projectSignals (array), deepScan (boolean) Detect skills in use by scanning package dependencies and source code (via gaia dev scan).
gaia_propose skillId (string, optional), name (string, optional), ... Submit a fusion claim or propose a novel skill, automatically opening a draft PR.

Tool Details

gaia_lookup

Performs exact ID matches or fuzzy searches against the registry index (registry/gaia.json and registry/named-skills.json).

Example Usage:

  • gaia_lookup({ query: "web-scrape" })
  • gaia_lookup({ query: "entity extraction" })

Returns the full JSON block of the skill, listing its tier, trust magnitude, prerequisite path, and registered evidence.

gaia_suggest

Suggests next-step skills or fusions that the developer is close to unlocking based on project metadata.

Example Usage:

  • gaia_suggest({ context: ["react", "frontend"], tools: ["web_search"] })

gaia_my_tree

Fetches user skill statistics from skill-trees/{username}.json. If no username is specified, falls back to the GAIA_USER environment variable or the local configuration default.

Example Usage:

  • gaia_my_tree({})
  • gaia_my_tree({ username: "john-doe" })

gaia_scan_context

Scans active files or dependencies for skill tokens. Setting deepScan: true invokes the local gaia dev scan CLI tool internally to search files for specific API usage or library patterns.

Example Usage:

  • gaia_scan_context({ connectedTools: ["read_file"], projectSignals: ["using cheerio to parse HTML"] })

gaia_propose

Submits a skill proposal or fusion claim directly to GitHub by creating a fork and opening a draft pull request.

Example Usage:

  • Propose a novel skill: 
    gaia_propose({
  "name": "structured-scraping",
  "description": "Extracting schema-conforming JSON using schema definitions in scrapers",
  "type": "extra",
  "prerequisites": ["web-scrape"]
})
  • Claim a fusion: 
    gaia_propose({
  "skillId": "structured-scraping",
  "prerequisites": ["web-scrape", "json-schema"]
})

Resources

The MCP server exposes standard resources allowing clients to pull complete registry data:

Resource URI Description
gaia://registry The complete, canonical skill registry graph JSON (registry/gaia.json)
gaia://tree/{username} The user-specific progress tree representation (skill-trees/{username}.json)

Architecture

The MCP server is developed as a TypeScript ESM module inside the packages/mcp/ directory:

packages/mcp/
├── bin/
│   └── gaia-mcp.ts           # Executable entrypoint (StdioServerTransport)
├── src/
│   ├── index.ts              # MCP Server definition and tool mappings
│   ├── daemon.ts             # Daemon manager (handles start/stop/status)
│   ├── config/               # Environment and local config merger
│   ├── resources/            # Registry and user-tree resource loaders
│   ├── tools/                # Implementations of individual MCP tools
│   │   ├── lookup.ts
│   │   ├── myTree.ts
│   │   ├── propose.ts
│   │   ├── scanContext.ts
│   │   └── suggest.ts
│   └── utils/                # Error handling and validation utilities

Key features of the architecture:

  • Fast Lookup: Uses in-memory structures constructed from pre-computed indexes (registry/gaia.json and registry/named-skills.json).
  • Daemon Lifecycle: When running in daemon mode via gaia dev mcp start, the process runs detached. A PID file is stored in ~/.gaia/mcp.pid and execution logs are captured in ~/.gaia/mcp.log.
  • Zod Schema Validation: Client input parameters are verified using strict Zod schemas inside src/index.ts to ensure type safety before calling backend code.

Environment Variables

The server behaves based on the following environment variable configuration:

Variable Optional/Required Purpose
GAIA_USER Recommended Identifies the default GitHub user for gaia_my_tree requests.
GITHUB_TOKEN Optional Needed by the gaia_propose tool to interact with GitHub APIs, fork the repository, and submit pull requests.
GAIA_REGISTRY_PATH Optional Specifies the absolute path to the main repository workspace. Set automatically by the python gaia dev wrapper.

Clone this wiki locally