MCP Server - Gennia

The Gennia MCP (@gennia/mcp) is a Model Context Protocol server that exposes all 135 Public API endpoints as tools your AI client (Cursor, Claude Code, Claude Desktop, Codex) can call directly. No clicks, no JSON copying. You ask in natural language — “list my agents”, “create a new plan at $100/month”, “upload this PDF as a knowledge source” — and the agent inside your IDE or chat handles it.

The server runs as a local subprocess via npx. The conversation happens between your AI client and the server on your machine; the only thing leaving your network is the authenticated HTTPS call to api.gennia.ai.

Quick install (one command)

The easiest path is to let the CLI handle it:

npm install -g @gennia/cli
gennia auth login
gennia mcp install

The command detects which AI clients you have installed, writes the right config block to each, and drops a SKILL.md in Claude Code’s skills directory so the agent “knows” about Gennia even in fresh sessions. Restart the AI client and you’re done.

Manual install

If you’d rather not use the CLI, it’s a JSON edit. Copy the snippet that matches your client.

Claude Code
Cursor
Claude Desktop
Codex CLI

Edit ~/.claude.json and add a mcpServers.gennia block:

{
  "mcpServers": {
    "gennia": {
      "command": "npx",
      "args": ["-y", "@gennia/mcp"],
      "env": {
        "GENNIA_API_KEY": "gsk_..."
      }
    }
  }
}

Or via Claude Code’s own CLI:

claude mcp add gennia --scope user \
  -e GENNIA_API_KEY=gsk_... \
  -- npx -y @gennia/mcp

Edit ~/.cursor/mcp.json (global) or .cursor/mcp.json at the project root:

{
  "mcpServers": {
    "gennia": {
      "command": "npx",
      "args": ["-y", "@gennia/mcp"],
      "env": {
        "GENNIA_API_KEY": "gsk_..."
      }
    }
  }
}

Edit the config file (path depends on your OS):

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "gennia": {
      "command": "npx",
      "args": ["-y", "@gennia/mcp"],
      "env": {
        "GENNIA_API_KEY": "gsk_..."
      }
    }
  }
}

Edit ~/.codex/config.toml and add a TOML block (Codex uses TOML, not JSON):

[mcp_servers.gennia]
command = "npx"
args = ["-y", "@gennia/mcp"]

[mcp_servers.gennia.env]
GENNIA_API_KEY = "gsk_..."

gennia mcp install doesn’t write the Codex TOML format yet. Hand-edit for now.

Environment

Variable	Default	What it does
`GENNIA_API_KEY`	— (required)	Workspace API key (`gsk_...`). Generate inside Studio → Settings → API Keys.
`GENNIA_BASE_URL`	`https://api.gennia.ai`	Override for dev (`https://api.dev.gennia.ai`) or a local backend (`http://localhost:8080`).

Tool catalog

The server reads the OpenAPI spec at startup and registers one MCP tool per operation. Naming is <tag>__<operationId> in snake_case.

Domain	Tools	Examples
Agents	6 + 60+ sub-groups	`agents__list_agents`, `agents__create_agent`, `agent_prompt__update_prompt`, `agent_channels__connect_channel`, …
Billing	15	`billing__list_plans`, `billing__create_coupon`, `billing__create_credit_package`
Clients	8	`clients__create_client`, `clients__suspend_client`, `clients__reactivate_client`
Hub	12	`hub__get_hub`, `hub__update_identity`, `hub__upload_logo`, `hub_external_links__create`
Conversations + Messages	5	`conversations__list_conversations`, `messages__send_message`
Knowledge / Skills / HTTP Tools / MCPs	25+	`knowledge_sources__upload_file`, `skills__upload_skill`, `http_tools__create_tool`
Misc	remaining	`ai_models__list_aimodels`, `public_api__health`, …

Every tool has an inputSchema derived from the operation’s parameters + request body in the OpenAPI spec. Your AI client’s LLM reads those schemas and builds the arguments on its own.

Example prompts

Once installed, you ask in natural language:

Read

List the 5 most recent agents in my workspace

The agent calls agents__list_agents with limit: 5.

Composition

Which billing plan has the most active subscriptions?

Lists plans, sorts by activeSubscriptions, hands you the answer.

File upload

Upload ./manual.pdf as a knowledge source named "Q4 Manual"

Calls knowledge_sources__upload_file with a local file_path.

Mutation with confirmation

Delete the PROMO50 coupon

Lists coupons, picks the publicId, asks for confirmation before calling billing__delete_coupon.

Endpoints not exposed

Endpoint	Why
`POST /agents/{id}/messages/stream`	Server-Sent Events — MCP doesn’t natively stream incremental tool results. Use the sync `POST /agents/{id}/messages`, which returns the full reply in one response.

Diagnose

If the server won’t connect or tools fail:

gennia mcp status

Expected output:

gennia mcp status (cli v0.3.1)
  ✓ Node version                       v22.22.0 (require >= 20)
  ✓ API reachable + key valid          workspace 86072856-...
  ✓ Latest @gennia/mcp on npm          0.3.1
  ✓ Claude Code MCP entry              configured
  ✓ Cursor MCP entry                   configured
  ✓ npx on PATH                        needed because the MCP servers spawn via `npx -y @gennia/mcp`

Any red ✗ points to the step to fix.

Update to the latest version

npx -y @gennia/mcp (no version pin) checks the npm registry daily and updates automatically. To force a refresh, clear the npx cache:

rm -rf ~/.npm/_npx

The next time your AI client launches the MCP server, it fetches the current version.

Next steps

Install the CLI

Same API, different surface. The CLI is the preferred channel for scripts, automation, and shell-driven AI agents.

Full reference

Every endpoint that becomes an MCP tool is documented here with schemas, try-it-out and examples.

​Quick install (one command)

​Manual install

​Environment

​Tool catalog

​Example prompts

Read

Composition

File upload

Mutation with confirmation

​Endpoints not exposed

​Diagnose

​Update to the latest version

​Next steps

Install the CLI

Full reference

Quick install (one command)

Manual install

Environment

Tool catalog

Example prompts

Endpoints not exposed

Diagnose

Update to the latest version

Next steps