okokumo nel tuo assistente IA

okokumo gestisce un server Model Context Protocol ufficiale e ospitato. Collegalo a un assistente IA e puoi chiedergli quali controlli sono giù, se sei stato avvisato, qual è stata la disponibilità di un controllo questa settimana — oppure fargli creare un controllo, metterne uno in pausa durante un deploy, o raccontare un incidente sulla tua pagina di stato.

È un sottile strato sopra l'API REST pubblica: ogni strumento è una chiamata a una rotta /v1, fatta a tuo nome — con un accesso dal browser o una chiave API — attraverso la stessa autenticazione, la stessa separazione per organizzazione, gli stessi controlli di ruolo e limiti di piano. Non può fare nulla che una chiave API non possa già fare via REST.

• Endpoint: https://app.okokumo.com/mcp, MCP Streamable HTTP
• Autenticazione: accesso dal browser (OAuth), al client basta l'URL; oppure una chiave API di okokumo, inviata come Authorization: Bearer sk_…
• Piani: tutti, Free incluso
• Limite di frequenza: il budget API della tua organizzazione, 120 richieste al minuto, condiviso con REST

1. Collegati accedendo dal browser (consigliato)

Claude, ChatGPT, Cursor, VS Code e Claude Code si collegano con il solo URL https://app.okokumo.com/mcp. Nessuna chiave da creare, incollare o tenere fuori da git.

1. Aggiungi okokumo al tuo client con quell'URL (client per client, qui sotto).
2. Il client apre okokumo nel tuo browser. Accedi, se non l'hai già fatto.
3. Una schermata di consenso mostra il nome dell'app, l'indirizzo a cui ti rimanderà, la tua organizzazione e cosa ottiene l'app: accesso completo, lo stesso di una chiave API, con il tuo ruolo. Approva o rifiuta. Approva solo una connessione che hai avviato tu.
4. Tornato nel client, trovi gli strumenti pronti.

Solo proprietari e amministratori possono approvare, la stessa regola della creazione di una chiave API. L'app viene collegata all'organizzazione indicata nella schermata di consenso, e solo a quella.

Claude (claude.ai, Claude Desktop)

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

ChatGPT

Nelle impostazioni dei connettori di ChatGPT, aggiungi un connettore personalizzato con lo stesso URL.

Claude Code

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

Poi esegui /mcp in Claude Code, scegli okokumo e accedi.

Cursor

In ~/.cursor/mcp.json o .cursor/mcp.json:

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

Cursor ti propone poi di accedere dalle sue impostazioni MCP.

VS Code

In .vscode/mcp.json:

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

VS Code ti chiede di accedere quando avvia il server.

Testati da un capo all'altro finora: Claude Code e MCP Inspector. claude.ai, ChatGPT, Cursor e VS Code implementano la stessa specifica di autorizzazione MCP, ma non sono ancora stati provati dal vivo con okokumo. Se uno di loro non funziona, faccelo sapere; nel frattempo una chiave API (sezione 3) funziona.

2. App collegate e revoca

Account → Connected apps elenca ogni app collegata alla tua organizzazione: il nome, chi l'ha collegata e quando, e quando è stata usata l'ultima volta. Ogni membro vede l'elenco; proprietari e amministratori possono revocare un'app da lì (Revoke). La revoca è immediata: l'app viene rifiutata alla sua richiesta successiva.

• I token di accesso durano un'ora e si rinnovano da soli. Un'app inutilizzata per 30 giorni va approvata di nuovo.
• Un reset della password, un account sospeso o la rimozione dall'organizzazione scollegano ogni app che quella persona aveva collegato.

3. Oppure usa una chiave API

Per script, CI e client senza accesso OAuth. Le chiavi API funzionano esattamente come prima, accanto alle app collegate.

Nella dashboard, Account → API keys (proprietari e amministratori). La chiave viene mostrata una sola volta.

• Una chiave agisce con il ruolo di chi l'ha creata. La chiave di un proprietario o di un amministratore può fare tutto quanto elencato sotto; quella di un membro può gestire i controlli ma non gli incidenti — esattamente come via REST.
• Usa una chiave per client — una per Claude Code, una per Cursor — così puoi revocarle singolarmente. La chiave è verificata a ogni richiesta: una chiave revocata scollega il client al suo messaggio successivo.
• La configurazione qui sotto contiene un segreto. Trattala come un file di password e tienila fuori da git.

4. Collega un client con una chiave

Sostituisci sk_… con la tua chiave.

Claude Code

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

Per un .mcp.json condiviso da tutto il progetto (--scope project), metti Bearer ${OKOKUMO_API_KEY} nell'intestazione ed esporta la variabile nella tua shell, così la chiave non finisce mai nel repository.

Claude Desktop

Il connettore personalizzato della sezione 1 non richiede chiavi. Per usare invece una chiave, collegati tramite il ponte mcp-remote (richiede Node.js) in 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_…" }
    }
  }
}

Il valore dell'intestazione passa da env perché alcune piattaforme dividono gli argomenti sullo spazio in Bearer sk_…. Riavvia Claude Desktop dopo la modifica.

Cursor

In ~/.cursor/mcp.json (tutti i progetti) o .cursor/mcp.json (un solo progetto):

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

Altri client

Qualsiasi client MCP che parli Streamable HTTP e possa inviare un'intestazione Authorization si collega allo stesso modo: l'endpoint qui sopra, la tua chiave come token bearer.

5. Cosa sa fare

18 strumenti: 10 in lettura, 8 in scrittura. Nessuno cancella nulla, nessuno tocca le chiavi API — le cancellazioni e la gestione delle chiavi restano nella dashboard.

• Lettura: il tuo account; i tuoi controlli; disponibilità e latenza di un controllo su un giorno, una settimana o un mese; i suoi cambi di stato; gli avvisi che ha inviato; i canali che avvisa; i tuoi canali; la tua pagina di stato e i suoi incidenti.
• Scrittura: creare un controllo, modificarlo, metterlo in pausa, riattivarlo, scegliere quali canali avvisa; creare un incidente, modificarlo, pubblicarne un aggiornamento.

Cosa cambia rispetto a chiamare REST direttamente, di proposito:

• Aggiornamenti parziali. Modificare un controllo o un incidente cambia solo i campi che indichi; lo strumento legge prima il record attuale e conserva il resto.
• Le durate sono in secondi. grace_seconds: 600 sono dieci minuti. Le descrizioni degli strumenti lo dicono, perché i minuti sono l'errore classico di un modello qui.
• URL di ping incluse. I controlli heartbeat e cron tornano con la ping_url che il job deve chiamare.
• I segreti dei canali restano fuori dalla conversazione. URL dei webhook, segreti di firma e ID delle chat Telegram non vengono mai restituiti.
• Argomenti rigorosi. Un argomento sconosciuto viene rifiutato con l'elenco di quelli accettati, invece di essere ignorato in silenzio.
• Le scritture sono segnalate. Ogni strumento dichiara se si limita a leggere o cosa modifica, così il tuo client può chiedere prima di eseguire una scrittura. Mettere in pausa un controllo o restringere l'instradamento dei suoi avvisi conta come distruttivo — significa avvisi che non partiranno — e il modello ha l'istruzione di chiederti conferma prima, e di pubblicare un incidente solo quando lo chiedi tu: gli incidenti nascono come bozze private.

6. Limiti ed errori

• Ogni richiesta a /mcp conta sulle 120 richieste al minuto della tua organizzazione — lo stesso budget di REST, e i due si sommano. Gli strumenti che leggono prima di scrivere (modificare, mettere in pausa o riattivare un controllo, modificare un incidente) contano doppio.
• Oltre il limite, l'assistente viene informato di quanti secondi attendere, e di non riprovare in un ciclo.
• Una chiamata rifiutata — un limite del piano, un ruolo non autorizzato, un ID inesistente — torna come un errore che il modello può leggere e spiegarti, terminato dallo stato HTTP.
• Una chiave sconosciuta o revocata riceve 401: crea una nuova chiave e aggiorna la configurazione del client. Un'app revocata riceve la stessa risposta e va approvata di nuovo.