Skip to main content

MCP Server

The Ggnomad MCP Server (ggnomad-mcp binary, from @ggnomad/mcp) exposes AI-assistant tools, resources, and prompts for the GGNomad platform via GraphQL. It is a thin shell over @burdenoff/mcp-libs.

Install​

npm install -g @ggnomad/mcp
# or
bun install -g @ggnomad/mcp

Binary: ggnomad-mcp

Environment selection​

The MCP server defaults to production endpoints. Set BURDENOFF_ENV before starting the server to target alpha or local:

BURDENOFF_ENVWorkspace endpointGlobal endpoint
prod (default)https://graphqlworkspaces.burdenoff.com/workspaces/graphqlhttps://graphql.burdenoff.com/global/graphql
alphahttps://alphagraphqlworkspaces.burdenoff.com/workspaces/graphqlhttps://alphagraphql.burdenoff.com/global/graphql
localhttp://localhost:4003/workspaces/graphqlhttp://localhost:4000/global/graphql

You can also override per variable:

VariableDefaultDescription
GGNOMAD_WORKSPACE_ENDPOINThttps://graphqlworkspaces.burdenoff.com/workspaces/graphqlWorkspace gateway
GGNOMAD_GLOBAL_ENDPOINThttps://graphql.burdenoff.com/global/graphqlGlobal gateway
GGNOMAD_API_KEY—API key auth (skips device code)
GGNOMAD_ACCESS_TOKEN—Pre-set access token
GGNOMAD_WORKSPACE_ID—Pre-select workspace
GGNOMAD_ORGANIZATION_ID—Pre-select organization
LOG_LEVELinfoLogging level (error/warn/info/debug)

Run​

Stdio transport (typical for Claude Desktop)​

ggnomad-mcp --stdio

HTTP transport (for remote clients)​

ggnomad-mcp --http --port 3030

What it exposes​

The server publishes tools in two groups:

  • Ggnomad tools — providers, properties, activities, events, tours, trips, bookings, favorites, analytics, and the rest of the GGNomad surface.
  • Burdenoff Workspaces platform tools — the shared capabilities your workspace has enabled, such as identity, workspaces and groups, files, tags, conversations, notifications, scheduling, integrations, export, and billing.

Tool / resource / prompt names are product-prefixed (ggnomad_*), so tools from different products can be mounted side by side in the same assistant without colliding. Every tool call is made with your token and is permission-checked exactly like the equivalent CLI or API call.

Claude Desktop integration​

Add to your Claude Desktop config (~/.claude/settings.json under mcpServers):

{
  "mcpServers": {
    "ggnomad": {
      "type": "stdio",
      "command": "ggnomad-mcp",
      "args": ["--stdio"],
      "env": {
        "BURDENOFF_ENV": "prod"
      }
    }
  }
}

Development​

cd ~/products/ggnomad/ggnomad-mcp
bun install           # Install dependencies
bun run dev           # Dev server (stdio, hot reload)
bun run server:http   # HTTP transport mode
bun run test          # Run wiring tests (vitest)
bun run sanity        # typecheck + lint + format + build
bun run build         # Production build

Run as a binary after building:

node dist/index.js               # stdio transport
node dist/index.js --http --port 3030

Mounted Modules​

auth, ggnomad, sandbox, rbac, organizations, tours, workspaces, groups, tags, files, conversations, security, integrations, channels, scheduler, export, notifications, support, products, devportal, billing, store.

Publishing​

Publishing is held (pre-launch). Pushing to main runs only the green gate (lint, typecheck, test, build). Publishing @ggnomad/mcp to npmjs happens only via the manual release.yml workflow (workflow_dispatch or a v* tag).