> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gennia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Plug any AI client (Cursor, Claude Code, Claude Desktop, Codex) into your Gennia workspace via a Model Context Protocol server. 135 tools, one per Public API endpoint.

The **Gennia MCP** ([`@gennia/mcp`](https://www.npmjs.com/package/@gennia/mcp)) is a [Model Context Protocol](https://modelcontextprotocol.io) 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.

<Note>
  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`.
</Note>

## Quick install (one command)

The easiest path is to let the [CLI](/en/api-reference/cli) handle it:

```bash theme={null}
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.

<Tabs>
  <Tab title="Claude Code">
    Edit `~/.claude.json` and add a `mcpServers.gennia` block:

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

    Or via Claude Code's own CLI:

    ```bash theme={null}
    claude mcp add gennia --scope user \
      -e GENNIA_API_KEY=gsk_... \
      -- npx -y @gennia/mcp
    ```
  </Tab>

  <Tab title="Cursor">
    Edit `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` at the project root:

    ```json theme={null}
    {
      "mcpServers": {
        "gennia": {
          "command": "npx",
          "args": ["-y", "@gennia/mcp"],
          "env": {
            "GENNIA_API_KEY": "gsk_..."
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Claude Desktop">
    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`

    ```json theme={null}
    {
      "mcpServers": {
        "gennia": {
          "command": "npx",
          "args": ["-y", "@gennia/mcp"],
          "env": {
            "GENNIA_API_KEY": "gsk_..."
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Codex CLI">
    Edit `~/.codex/config.toml` and add a TOML block (Codex uses TOML, not JSON):

    ```toml theme={null}
    [mcp_servers.gennia]
    command = "npx"
    args = ["-y", "@gennia/mcp"]

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

    <Tip>
      `gennia mcp install` doesn't write the Codex TOML format yet. Hand-edit for now.
    </Tip>
  </Tab>
</Tabs>

## 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](/api-reference/openapi.json) 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:

<CardGroup cols={2}>
  <Card title="Read">
    ```
    List the 5 most recent agents in my workspace
    ```

    The agent calls `agents__list_agents` with `limit: 5`.
  </Card>

  <Card title="Composition">
    ```
    Which billing plan has the most active subscriptions?
    ```

    Lists plans, sorts by `activeSubscriptions`, hands you the answer.
  </Card>

  <Card title="File upload">
    ```
    Upload ./manual.pdf as a knowledge source named "Q4 Manual"
    ```

    Calls `knowledge_sources__upload_file` with a local `file_path`.
  </Card>

  <Card title="Mutation with confirmation">
    ```
    Delete the PROMO50 coupon
    ```

    Lists coupons, picks the `publicId`, asks for confirmation before calling `billing__delete_coupon`.
  </Card>
</CardGroup>

## 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:

```bash theme={null}
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:

```bash theme={null}
rm -rf ~/.npm/_npx
```

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

## Next steps

<CardGroup cols={2}>
  <Card title="Install the CLI" icon="terminal" href="/en/api-reference/cli">
    Same API, different surface. The CLI is the preferred channel for scripts, automation, and shell-driven AI agents.
  </Card>

  <Card title="Full reference" icon="book" href="/en/api-reference/introduction">
    Every endpoint that becomes an MCP tool is documented here with schemas, try-it-out and examples.
  </Card>
</CardGroup>