> ## 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 > Conecte qualquer cliente AI (Cursor, Claude Code, Claude Desktop, Codex) ao seu workspace Gennia com um servidor MCP. 135 ferramentas, uma por endpoint da Public API. O **Gennia MCP** ([`@gennia/mcp`](https://www.npmjs.com/package/@gennia/mcp)) é um servidor [Model Context Protocol](https://modelcontextprotocol.io) 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](/pt/api-reference/cli) cuidar disso: ```bash theme={null} 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. Edite `~/.claude.json` e adicione o bloco `mcpServers.gennia`: ```json theme={null} { "mcpServers": { "gennia": { "command": "npx", "args": ["-y", "@gennia/mcp"], "env": { "GENNIA_API_KEY": "gsk_..." } } } } ``` Alternativa via CLI do próprio Claude Code: ```bash theme={null} 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: ```json theme={null} { "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` ```json theme={null} { "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): ```toml theme={null} [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](/api-reference/openapi.json) na inicialização e cria uma ferramenta MCP por operação. Naming é `__` 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: ``` Lista os 5 agentes mais recentes do meu workspace ``` O agente chama `agents__list_agents` com `limit: 5`. ``` Qual o plano com mais assinaturas ativas? ``` Lista planos, ordena por `activeSubscriptions`, te dá a resposta. ``` Sobe ./manual.pdf como knowledge source chamado "Manual Q4" ``` Chama `knowledge_sources__upload_file` com `file_path` local. ``` 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: ```bash theme={null} 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: ```bash theme={null} 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 Mesma API, surface diferente. O CLI é o canal preferido pra scripts, automações e agentes IA com acesso ao shell. Cada endpoint que vira tool MCP está documentado aqui com schemas, try-it-out e exemplos.