Você conectou o Cabgo ao ChatGPT, Claude ou Cursor por meio do servidor MCP dele. Na primeira vez que o operador pede «crie meu app de delivery», o agente devolve um erro porque tentou chamar uma ferramenta de descoberta antes da de criação. Na segunda vez, depois de criar dois apps, ele não passa o tenantId na ação seguinte e o servidor responde com tenant_mismatch. Na terceira, recebe o cartão de confirmação de Tier-4 e o trata como um erro que dá para tentar de novo. Todos esses tropeços têm uma causa em comum: o agente está aprendendo as convenções do catálogo por tentativa e erro.
Publicamos um skill público que resolve isso. É um arquivo SKILL.md sob licença MIT em github.com/CabgoApp/cabgo-mcp-operator-skill que qualquer agente pode carregar para operar o servidor MCP do Cabgo corretamente desde a primeira chamada.
As cinco convenções que o skill ensina
O skill carrega essas convenções como contexto do agente quando detecta que a tarefa é do Cabgo:
- O bearer se vincula a um usuário, não a um tenant: um operador rotineiramente possui múltiplos apps (táxi e delivery, por exemplo) e o mesmo token cobre todos
- Sempre há um tenant padrão persistente quando o operador tem pelo menos um: o primeiro cabgo_create_my_app se promove sozinho, cabgo_set_default_tenant permite trocá-lo depois
- tenantId é um argumento opcional em cada ferramenta de dashboard: aceita tanto o UUID quanto o slug (pidelo-express, taxi-express), e o servidor o promove ao header X-Cabgo-Tenant
- O operador recém-conectado sem apps é um estado válido do fluxo: as únicas ferramentas chamáveis são as públicas mais cabgo_create_my_app e cabgo_list_my_tenants
- As ferramentas destrutivas usam confirmação em duas etapas com HMAC e TTL de cinco minutos: o cartão de Tier-4 não é um erro, é a etapa de confirmação antes de executar
Antes e depois do skill
Sem o skill, um agente conectado ao MCP do Cabgo aprende os padrões por tentativa e erro. Perde tokens em chamadas de descoberta prévias, recebe erros de tenant_mismatch que precisa interpretar, tenta de novo em loop diante de cartões de confirmação e às vezes sugere gerar links de Stripe dentro do chat — o que violaria as políticas de comércio da OpenAI e da Anthropic. Com o skill carregado, esses mesmos erros desaparecem porque o agente sabe de antemão qual ferramenta corresponde a cada intenção do operador e qual padrão seguir para as operações destrutivas ou multi-tenant.
Como instalá-lo no seu agente
O skill é distribuído como um único arquivo markdown. Três caminhos de instalação de acordo com o cliente do agente:
- Claude Code global: baixe o SKILL.md para ~/.claude/skills/cabgo-mcp-operator/ e ele é ativado automaticamente em qualquer projeto quando o agente detecta uma tarefa do Cabgo
- Claude Code por projeto: o mesmo arquivo dentro de .claude/skills/cabgo-mcp-operator/ do repositório limita o alcance a esse projeto
- Claude Desktop: deixe o arquivo em ~/Library/Application Support/Claude/skills/ no macOS ou no caminho equivalente em outros sistemas
- ChatGPT e Cursor: cole o conteúdo do SKILL.md no campo de instruções personalizadas do cliente — continua funcionando como referência, ainda que sem auto-trigger
Comandos exatos para Claude Code
Cole o bloco no seu terminal e ele fica instalado no nível global. O agente o carrega automaticamente quando detectar uma tarefa do Cabgo em qualquer projeto.
Para restringir o skill a um único projeto, repita o mesmo comando, mas apontando para o caminho .claude/skills/cabgo-mcp-operator/ dentro do repositório em questão. O arquivo é idêntico; só muda o alcance.
Conectar o servidor MCP do Cabgo
O skill sozinho explica as convenções, mas o agente precisa estar conectado ao servidor MCP para realmente executar as ferramentas. A URL é a mesma em todos os clientes:
Passos por cliente:
- ChatGPT: Settings → Apps & Connectors → Developer Mode → Add custom connector → colar https://www.cabgo.app/mcp e autorizar com o Google
- Claude Desktop: Settings → Connectors → Add custom connector → colar a mesma URL → concluir o OAuth
- Cursor: Cursor Settings → MCP → Add new server → colar a URL e concluir o OAuth no navegador
- Claude Code (CLI): o arquivo claude_desktop_config.json aceita uma entrada do tipo http com a URL do servidor
O primeiro login cria automaticamente a conta de operador: não é preciso se cadastrar antes em cabgo.app. Uma vez autorizado, o agente pode chamar imediatamente cabgo_create_my_app e a conversa lança o primeiro app.
O que vem a seguir
O catálogo do MCP do Cabgo cresce à medida que novas ferramentas são adicionadas (auto-resolução de tenant padrão persistente, atribuição de origem de criação, locale-update por chat). O skill se mantém como um arquivo único sob controle de versão para que qualquer integrador possa fazer um fork dele, adicionar convenções específicas da sua operação e compartilhar melhorias com a comunidade. Para integradores que constroem sobre a API REST do Cabgo, o skill complementa a documentação interativa em cabgo.app/api-docs porque cobre o comportamento do agente, não apenas o contrato do servidor.
O repositório está aberto em github.com/CabgoApp/cabgo-mcp-operator-skill. As issues e os pull requests chegam ao mesmo lugar.
