okokumo no seu assistente de IA

A okokumo opera um servidor Model Context Protocol oficial e alojado. Ligue-o a um assistente de IA e pode perguntar-lhe que verificações estão em baixo, se foi alertado, qual foi a disponibilidade de uma verificação esta semana — ou pedir-lhe que crie uma verificação, que pause uma durante um deploy, ou que narre um incidente na sua página de estado.

É uma camada fina sobre a API REST pública: cada ferramenta é uma chamada a uma rota /v1, feita em seu nome — através de um início de sessão no navegador ou de uma chave de API — com a mesma autenticação, a mesma separação por organização, as mesmas verificações de papel e os mesmos limites de plano. Não pode fazer nada que uma chave de API não possa já fazer por REST.

• Endpoint: https://app.okokumo.com/mcp, MCP Streamable HTTP
• Autenticação: início de sessão no navegador (OAuth), o cliente só precisa do URL; ou uma chave de API da okokumo, enviada como Authorization: Bearer sk_…
• Planos: todos, Free incluído
• Limite de pedidos: o orçamento de API da sua organização, 120 pedidos por minuto, partilhado com o REST

1. Ligue iniciando sessão (recomendado)

O Claude, o ChatGPT, o Cursor, o VS Code e o Claude Code ligam-se apenas com o URL https://app.okokumo.com/mcp. Não há chave para criar, colar ou manter fora do git.

1. Adicione a okokumo ao seu cliente com esse URL (por cliente, abaixo).
2. O cliente abre a okokumo no seu navegador. Inicie sessão, se ainda não o fez.
3. Um ecrã de consentimento mostra o nome da aplicação, o endereço para onde o vai reenviar, a sua organização e o que a aplicação recebe: acesso total, o mesmo de uma chave de API, com o seu papel. Aprove ou recuse. Aprove apenas uma ligação que tenha sido você a iniciar.
4. De volta ao cliente, as ferramentas estão disponíveis.

Só proprietários e administradores podem aprovar, a mesma regra que para criar uma chave de API. A aplicação fica ligada à organização indicada no ecrã de consentimento, e só a essa.

Claude (claude.ai, Claude Desktop)

Settings → Connectors → Add custom connector, com o URL https://app.okokumo.com/mcp.

ChatGPT

Nas definições de conectores do ChatGPT, adicione um conector personalizado com o mesmo URL.

Claude Code

claude mcp add --transport http okokumo https://app.okokumo.com/mcp

Depois execute /mcp no Claude Code, escolha a okokumo e inicie sessão.

Cursor

Em ~/.cursor/mcp.json ou .cursor/mcp.json:

{
  "mcpServers": {
    "okokumo": { "url": "https://app.okokumo.com/mcp" }
  }
}

O Cursor propõe depois iniciar sessão a partir das suas definições de MCP.

VS Code

Em .vscode/mcp.json:

{
  "servers": {
    "okokumo": { "type": "http", "url": "https://app.okokumo.com/mcp" }
  }
}

O VS Code pede-lhe para iniciar sessão quando arranca o servidor.

Testados de ponta a ponta até agora: Claude Code e MCP Inspector. O claude.ai, o ChatGPT, o Cursor e o VS Code implementam a mesma especificação de autorização MCP, mas ainda não foram experimentados em real com a okokumo. Se algum falhar, diga-nos; entretanto, uma chave de API (secção 3) funciona.

2. Aplicações ligadas e revogação

Account → Connected apps lista todas as aplicações ligadas à sua organização: o nome, quem a ligou e quando, e quando foi usada pela última vez. Todos os membros veem a lista; proprietários e administradores podem revogar uma aplicação aí (Revoke). A revogação é imediata: a aplicação é recusada no pedido seguinte.

• Os tokens de acesso duram uma hora e renovam-se sozinhos. Uma aplicação sem uso durante 30 dias tem de ser aprovada de novo.
• Uma reposição de palavra-passe, uma conta suspensa ou a saída da organização desliga todas as aplicações que essa pessoa ligou.

3. Ou use uma chave de API

Para scripts, CI e clientes sem início de sessão OAuth. As chaves de API funcionam exatamente como antes, ao lado das aplicações ligadas.

No painel, Account → API keys (proprietários e administradores). A chave é mostrada uma única vez.

• Uma chave age com o papel de quem a criou. A chave de um proprietário ou administrador pode fazer tudo o que está listado abaixo; a de um membro pode gerir verificações mas não incidentes — exatamente como por REST.
• Use uma chave por cliente — uma para o Claude Code, outra para o Cursor — para poder revogar cada uma em separado. A chave é verificada em cada pedido: uma chave revogada desliga o cliente na sua mensagem seguinte.
• A configuração abaixo contém um segredo. Trate-a como um ficheiro de palavras-passe e mantenha-a fora do git.

4. Ligue um cliente com uma chave

Substitua sk_… pela sua chave.

Claude Code

claude mcp add --transport http okokumo https://app.okokumo.com/mcp \
  --header "Authorization: Bearer sk_…"
claude mcp get okokumo

Para um .mcp.json de todo o projeto (--scope project), ponha Bearer ${OKOKUMO_API_KEY} no cabeçalho e exporte a variável na sua shell, para que a chave nunca vá parar ao repositório.

Claude Desktop

O conector personalizado da secção 1 não precisa de chave. Para usar uma chave em vez disso, ligue através da ponte mcp-remote (requer Node.js) em claude_desktop_config.json:

{
  "mcpServers": {
    "okokumo": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://app.okokumo.com/mcp",
               "--header", "Authorization:${OKOKUMO_AUTH}"],
      "env": { "OKOKUMO_AUTH": "Bearer sk_…" }
    }
  }
}

O valor do cabeçalho passa por env porque algumas plataformas dividem os argumentos no espaço de Bearer sk_…. Reinicie o Claude Desktop depois de editar.

Cursor

Em ~/.cursor/mcp.json (todos os projetos) ou .cursor/mcp.json (um projeto):

{
  "mcpServers": {
    "okokumo": {
      "url": "https://app.okokumo.com/mcp",
      "headers": { "Authorization": "Bearer sk_…" }
    }
  }
}

Outros clientes

Qualquer cliente MCP que fale Streamable HTTP e consiga enviar um cabeçalho Authorization liga da mesma forma: o endpoint acima, a sua chave como token bearer.

5. O que consegue fazer

18 ferramentas: 10 de leitura, 8 de escrita. Nenhuma apaga nada, nenhuma mexe nas chaves de API — apagar e gerir chaves fica no painel.

• Leitura: a sua conta; as suas verificações; a disponibilidade e a latência de uma verificação num dia, numa semana ou num mês; as suas mudanças de estado; os alertas que enviou; os canais que alerta; os seus canais; a sua página de estado e os seus incidentes.
• Escrita: criar uma verificação, alterá-la, pausá-la, retomá-la, escolher que canais alerta; criar um incidente, alterá-lo, publicar uma atualização.

O que difere de chamar o REST diretamente, de propósito:

• Atualizações parciais. Editar uma verificação ou um incidente muda apenas os campos que indicar; a ferramenta lê primeiro o registo atual e mantém o resto.
• As durações são em segundos. grace_seconds: 600 são dez minutos. As descrições das ferramentas dizem-no, porque os minutos são o erro clássico de um modelo aqui.
• URL de ping incluídos. As verificações heartbeat e cron voltam com o ping_url que o job tem de chamar.
• Os segredos dos canais ficam fora da conversa. URL de webhook, segredos de assinatura e IDs de chat do Telegram nunca são devolvidos.
• Argumentos estritos. Um argumento desconhecido é recusado com a lista dos aceites, em vez de ser ignorado em silêncio.
• As escritas estão assinaladas. Cada ferramenta declara se apenas lê ou o que altera, para que o seu cliente possa perguntar antes de executar uma escrita. Pausar uma verificação ou restringir o encaminhamento dos seus alertas conta como destrutivo — são alertas que não serão enviados — e o modelo tem instruções para confirmar consigo primeiro, e para publicar um incidente só quando o pedir: os incidentes começam como rascunhos privados.

6. Limites e erros

• Cada pedido a /mcp conta para os 120 pedidos por minuto da sua organização — o mesmo orçamento do REST, e os dois somam-se. As ferramentas que leem antes de escrever (alterar, pausar ou retomar uma verificação, alterar um incidente) contam a dobrar.
• Acima do limite, o assistente fica a saber quantos segundos esperar, e que não deve repetir em ciclo.
• Uma chamada recusada — um limite do plano, um papel sem permissão, um ID que não existe — volta como um erro que o modelo pode ler e explicar-lhe, terminado com o estado HTTP.
• Uma chave desconhecida ou revogada recebe 401: crie uma chave nova e atualize a configuração do cliente. Uma aplicação revogada recebe a mesma resposta e tem de ser aprovada de novo.