@gx/mcp — MCP Server for gx Knowledge Base

An MCP (Model Context Protocol) server that wraps the gx API so AI coding agents (Claude Code, Cursor, Windsurf, etc.) can pull knowledge base context during tasks.

What it does

Exposes four tools to any MCP-compatible agent:

| Tool | Description | |---|---| | list_documents | List all documents in a KB — returns id, filename, type, title | | get_document | Get full content of a document (frontmatter + body) | | search_documents | Client-side search across filename, title, type and frontmatter | | lint_document | Run gx lint rules on raw markdown content |

Prerequisites

• Node.js 18+
• A running gx-server instance

Build

cd packages/gx-mcp
pnpm install
pnpm build

Run

# Using defaults (Vercel-deployed server)
node dist/index.js

# With custom server
GX_SERVER_URL=http://localhost:3001 GX_API_KEY=my-key node dist/index.js

# Or via binary (after install)
gx-mcp

Environment variables

| Variable | Default | Description | |---|---|---| | GX_SERVER_URL | https://gx-server-condorcomputing.vercel.app | gx-server base URL | | GX_API_KEY | gx-dev-api-key | API key (passed as x-api-key header) | | GX_KB_ID | 78e0bc0f-38ba-4494-bcd3-416ea4532280 | Default knowledge base ID |

Configure with Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "gx": {
      "command": "node",
      "args": ["/path/to/gx/packages/gx-mcp/dist/index.js"],
      "env": {
        "GX_SERVER_URL": "https://gx-server-condorcomputing.vercel.app",
        "GX_API_KEY": "gx-dev-api-key",
        "GX_KB_ID": "78e0bc0f-38ba-4494-bcd3-416ea4532280"
      }
    }
  }
}

Or using npx after publishing:

{
  "mcpServers": {
    "gx": {
      "command": "npx",
      "args": ["-y", "@gx/mcp"],
      "env": {
        "GX_SERVER_URL": "https://gx-server-condorcomputing.vercel.app",
        "GX_API_KEY": "gx-dev-api-key"
      }
    }
  }
}

Configure with Cursor

In .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "gx": {
      "command": "node",
      "args": ["/path/to/gx/packages/gx-mcp/dist/index.js"],
      "env": {
        "GX_SERVER_URL": "https://gx-server-condorcomputing.vercel.app",
        "GX_KB_ID": "78e0bc0f-38ba-4494-bcd3-416ea4532280"
      }
    }
  }
}

Tool Examples

list_documents

// Input
{ "kb_id": "78e0bc0f-38ba-4494-bcd3-416ea4532280" }

// Output
[
  { "id": "abc123", "filename": "auth-decision.md", "type": "decision", "title": "Use JWT for Auth" },
  { "id": "def456", "filename": "onboarding.md", "type": "guide", "title": "Getting Started" }
]

get_document

// Input
{ "document_id": "abc123" }

// Output
{
  "id": "abc123",
  "filename": "auth-decision.md",
  "type": "decision",
  "title": "Use JWT for Auth",
  "frontmatter": { "type": "decision", "title": "Use JWT for Auth", "status": "accepted" },
  "content": "---\ntype: decision\n...\n\n# Use JWT for Auth\n\n..."
}

search_documents

// Input
{ "kb_id": "78e0bc0f-...", "query": "auth", "type": "decision" }

// Output
[
  { "id": "abc123", "filename": "auth-decision.md", "type": "decision", "title": "Use JWT for Auth" }
]

lint_document

// Input
{ "content": "# My Doc\n\nSome content without frontmatter" }

// Output
[
  { "ruleId": "GX001", "severity": "error", "message": "Missing frontmatter", "line": null }
]