MCP Server

O Gennia MCP (@gennia/mcp) é um servidor Model Context Protocol que expõe todos os 135 endpoints da Public API como ferramentas que seu cliente AI (Cursor, Claude Code, Claude Desktop, Codex) consegue chamar diretamente. Sem clique, sem cópia de JSON. Você pergunta em linguagem natural “lista meus agentes”, “cria um novo plano de R$ 100 / mês”, “sobe esse PDF como knowledge source” — e o agente da sua IDE / chat resolve sozinho.

O servidor roda como subprocess local via npx. Toda a conversa fica entre seu cliente AI e o servidor na sua máquina; a única coisa que sai pela rede são as chamadas HTTPS pra api.gennia.ai (autenticadas com sua API key).

Instalação rápida (1 comando)

A forma mais fácil é deixar o CLI cuidar disso:

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

O comando detecta quais clientes AI você tem instalados, escreve a configuração no arquivo certo de cada um, e ainda copia um SKILL.md no diretório de skills do Claude Code (assim o agente “sabe” sobre Gennia mesmo em sessões novas). Reinicia o cliente AI e pronto.

Instalação manual

Se preferir não usar o CLI, é uma edição de JSON num arquivo. Copie o snippet que combina com seu cliente.

Claude Code
Cursor
Claude Desktop
Codex CLI

Edite ~/.claude.json e adicione o bloco mcpServers.gennia:

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

Alternativa via CLI do próprio Claude Code:

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

Edite ~/.cursor/mcp.json (global) ou .cursor/mcp.json na raiz do projeto:

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

Edite o arquivo de configuração (caminho depende do sistema):

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_..."
      }
    }
  }
}

Edite ~/.codex/config.toml e adicione um bloco TOML (Codex usa TOML, não JSON):

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

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

O gennia mcp install ainda não escreve no formato TOML do Codex. Por enquanto, edição manual.

Variáveis de ambiente

Variável	Default	O que faz
`GENNIA_API_KEY`	— (obrigatório)	API key do workspace (`gsk_...`). Gere em Studio → Settings → API Keys.
`GENNIA_BASE_URL`	`https://api.gennia.ai`	Override pra dev (`https://api.dev.gennia.ai`) ou backend local (`http://localhost:8080`).

Catálogo de ferramentas

O servidor lê o OpenAPI spec na inicialização e cria uma ferramenta MCP por operação. Naming é <tag>__<operationId> em snake_case.

Domínio	Ferramentas	Exemplos
Agents	6 + 60+ subgrupos	`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`
Outros	restantes	`ai_models__list_aimodels`, `public_api__health`, …

Cada ferramenta tem um inputSchema derivado dos parâmetros + request body da OpenAPI. O LLM do seu cliente AI lê esses schemas e monta os argumentos sozinho.

Exemplos de prompts

Uma vez instalado, você pergunta em linguagem natural:

Leitura

Lista os 5 agentes mais recentes do meu workspace

O agente chama agents__list_agents com limit: 5.

Composição

Qual o plano com mais assinaturas ativas?

Lista planos, ordena por activeSubscriptions, te dá a resposta.

Upload de arquivo

Sobe ./manual.pdf como knowledge source chamado "Manual Q4"

Chama knowledge_sources__upload_file com file_path local.

Mutação com confirmação

Deleta o cupom PROMO50

Lista cupons, identifica o publicId, te pede confirmação antes de chamar billing__delete_coupon.

Endpoints não expostos

Endpoint	Por quê
`POST /agents/{id}/messages/stream`	Server-Sent Events — MCP não streama tool results de forma incremental. Use a versão síncrona `POST /agents/{id}/messages` que retorna a resposta completa.

Diagnosticar

Se o servidor não conectar ou as ferramentas falharem:

gennia mcp status

Saída esperada:

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`

Qualquer ✗ vermelho aponta o passo onde ajustar.

Atualizar pra versão mais recente

O npx -y @gennia/mcp (sem version pin) verifica o registro do npm diariamente e atualiza automaticamente. Pra forçar uma atualização imediata, limpe o cache do npx:

rm -rf ~/.npm/_npx

Na próxima vez que seu cliente AI lançar o servidor MCP, ele baixa a versão atual.

Próximos passos

Instalar o CLI

Mesma API, surface diferente. O CLI é o canal preferido pra scripts, automações e agentes IA com acesso ao shell.

Referência completa

Cada endpoint que vira tool MCP está documentado aqui com schemas, try-it-out e exemplos.

Começando

Convenções

Agents

Threads

Hub

Instalação rápida (1 comando)

Instalação manual

Variáveis de ambiente

Catálogo de ferramentas

Exemplos de prompts

Leitura

Composição

Upload de arquivo

Mutação com confirmação

Endpoints não expostos

Diagnosticar

Atualizar pra versão mais recente

Próximos passos

Instalar o CLI

Referência completa

​Instalação rápida (1 comando)

​Instalação manual

​Variáveis de ambiente

​Catálogo de ferramentas

​Exemplos de prompts

Leitura

Composição

Upload de arquivo

Mutação com confirmação

​Endpoints não expostos

​Diagnosticar

​Atualizar pra versão mais recente

​Próximos passos

Instalar o CLI

Referência completa

Instalação rápida (1 comando)

Instalação manual

Variáveis de ambiente

Catálogo de ferramentas

Exemplos de prompts

Endpoints não expostos

Diagnosticar

Atualizar pra versão mais recente

Próximos passos