Referência

Servidor MCP

Use a API Pública V1 por dentro de agentes de IA (Claude, Zed, Cursor, automações) sem escrever HTTP: o Gens CRM publica um servidor MCP (Model Context Protocol) que conversa por JSON-RPC 2.0 sobre POST.

URL do servidor MCP: https://api.crm.agenciagens.com.br/mcp
Autenticação: a mesma API Key da clínica, em Authorization: Bearer.
Transporte: Streamable HTTP stateless — uma mensagem JSON-RPC por POST; sem sessão, sem WebSocket.

Como o agente enxerga a API#

O servidor expõe ferramentas nomeadas para as operações de maior uso (gens_listContacts, gens_createContact, gens_getAccount, gens_moveContact, …) e uma ferramenta genérica gens_api_request que aceita qualquer rota da V1 (método + caminho), sempre validada contra o catálogo oficial.

Toda chamada passa pelo mesmo pipeline da API: escopos da chave, rate limit (120 leituras e 30 escritas por minuto), Idempotency-Key automática em escritas e auditoria de mutações. Se a chave não tem o escopo, o agente recebe o mesmo 403 insufficient_scope da API REST.

Primeiro teste (sem agente)#

bash

curl -sS -X POST "https://api.crm.agenciagens.com.br/mcp" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GENS_CLINIC_API_KEY" \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'

Esperado: result.protocolVersion + result.serverInfo. Depois liste as ferramentas com {"jsonrpc":"2.0","id":2,"method":"tools/list"} e chame uma:

json

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"gens_listContacts","arguments":{"limit":5}}}

Configurando em um cliente MCP#

A chave vive na variável de ambiente GENS_CLINIC_API_KEY da máquina onde o cliente MCP roda; ela nunca é embutida na URL. Exemplo genérico de configuração (clientes com suporte a headers):

json

{
  "mcpServers": {
    "gens-crm": {
      "url": "https://api.crm.agenciagens.com.br/mcp",
      "headers": {
        "Authorization": "Bearer ${GENS_CLINIC_API_KEY}"
      }
    }
  }
}

Segurança#

A chave é da clínica e vive na configuração do cliente MCP (variável de ambiente), nunca no navegador.
Sem CORS: somente processos locais/servidores consomem o endpoint.
As regras de Segurança e LGPD valem integralmente para o uso via MCP.