Nouveau · l'app mobile, second appareil pour relire et signer chaque ordre
kantamaSe connecterCréer un espace

API publique

La console parle au serveur central par son API /v1, avec une session ouverte par passkey. Quelques points servent sans session, à vos applications et à vos outils : les voici, tels que le central les sert.

6 minutesMis à jour le 18 novembre 2026

Les points sans session

PointSert àAccès
GET /v1/santeSavoir si le central répond : {"ok": true}.libre
GET /v1/public/statut/{espace}La page de statut publique d'un espace.libre, si l'espace a publié un projet
GET|POST|HEAD /v1/signal/{jeton}Les signaux des tâches planifiées.jeton secret de la tâche
POST /v1/sentry/api/{n}/envelope/, …/store/Les erreurs de vos applications, envoyées par les SDK Sentry.clé du DSN
POST /mcpLe serveur MCP des assistants.jeton kmcp_…

Tout le reste de /v1 exige la session de la console, ouverte par passkey : ce n'est pas une API à appeler depuis un script.

Page de statut publique

Sans session, mise en cache 30 secondes, affichée par la console sur /statut/<espace>. Un projet n'y figure que si l'espace l'a publié ; sans projet publié : 404.

GET /v1/public/statut/{espace}
{"espace": "Atelier exemple", "maj_le": 1794…, "en_panne": 0, "premier_jour": 1786…,
 "projets": [{"nom": "CAS-MARKET", "composants": [
   {"nom": "web · production", "etat": "ok", "disponibilite": 99.98, "jours": ["ok", "", "a", …]}]}],
 "incidents": [{"projet": "CAS-MARKET", "service": "api", "debut": 1794…, "fin": 1794…, "en_cours": false}]}

etat vaut ok, panne ou inconnu. Jamais d'adresse sondée, de domaine, d'hôte, de port, de message d'erreur ni d'identifiant interne.

Signaux des tâches planifiées

Vos tâches (déclarées sous jobs) signalent leur début, leur réussite ou leur échec. <url>/start, <url> (réussite), <url>/fail, ou <url>/<code> (0 : réussite, 1 à 255 : échec). La réponse est OK ; le corps n'est pas lu, ni l'adresse IP ni les en-têtes ne sont gardés.

cron · le serveur
# l'URL est créée dans la console (Tâches planifiées) et montrée une seule fois
curl -fsS https://kantama.app/v1/signal/<jeton>/start
./rapprochement.sh && curl -fsS https://kantama.app/v1/signal/<jeton> \
                   || curl -fsS https://kantama.app/v1/signal/<jeton>/fail

Erreurs au format Sentry

Créez un DSN pour le projet dans la console (Erreurs), puis donnez-le à votre SDK Sentry : https://<clé>@<hôte>/v1/sentry/<n>. Aucun compte Sentry n'est nécessaire.

  • 1 Mio par requête, avant et après décompression ; 256 Kio par événement (413 au-delà).
  • 300 événements par minute et par projet (429 avec Retry-After: 60).
  • Clé inconnue : 403. Projet inconnu : 404.

Serveur MCP et jetons kmcp_

Un assistant (Claude Code, Claude Desktop…) consulte et prépare ; il ne peut ni signer, ni approuver, ni transmettre. Le point /mcp parle le transport Streamable HTTP, sans état.

Créez un jeton dans Accès des assistants (MCP) : portée lecture ou preparation, durée 7, 30, 90 ou 365 jours. Il est montré une fois ; le central n'en garde que le SHA-256. La révocation est immédiate.

Terminal
claude mcp add --transport http kantama https://kantama.app/mcp \
  --header "Authorization: Bearer kmcp_…"
# client de bureau qui ne lance que des serveurs stdio :
KANTAMA_MCP_JETON=kmcp_… python pont_mcp.py https://kantama.app/mcp

Le pont pont_mcp.py n'utilise que la bibliothèque standard de Python 3.10 ou plus : copiez-le tel quel.

pont_mcp.py
"""Pont stdio → serveur MCP de Kantama, pour les clients de bureau qui ne lancent que des serveurs stdio.

Claude Code parle directement au point HTTP (`claude mcp add --transport http … --header …`). D'autres clients
de bureau ne savent que lancer une commande locale et lui parler sur son entrée et sa sortie standard : ce
fichier, sans aucune dépendance (bibliothèque standard de Python 3.10+), relaie chaque message JSON-RPC reçu
sur stdin vers `POST <url>` avec le jeton, et écrit la réponse sur stdout. Il ne garde rien et ne décide rien.

    KANTAMA_MCP_JETON=kmcp_… python pont_mcp.py https://central.exemple.com/mcp

Le jeton est lu dans l'environnement (jamais en argument : il serait visible dans la liste des processus).
"""

from __future__ import annotations

import base64
import json
import os
import sys
import urllib.error
import urllib.request

CLE_VERSION = "io.modelcontextprotocol/protocolVersion"
AVEC_NOM = ("tools/call", "resources/read", "prompts/get")


def _valeur_entete(v: str) -> str:
    """Spécification 2026-07-28 : une valeur non ASCII imprimable passe en base64 « =?base64?…?= »."""
    if v and all(0x20 <= ord(c) <= 0x7E for c in v) and v == v.strip() and not (v.startswith("=?base64?") and v.endswith("?=")):
        return v
    return "=?base64?" + base64.b64encode(v.encode()).decode() + "?="


class Pont:
    def __init__(self, url: str, jeton: str) -> None:
        self.url, self.jeton = url, jeton
        self.version_poignee: str | None = None  # version négociée par `initialize` (époque 2025)

    def entetes(self, m: dict) -> dict[str, str]:
        h = {"Content-Type": "application/json", "Accept": "application/json, text/event-stream", "Authorization": f"Bearer {self.jeton}"}
        params = m.get("params") if isinstance(m.get("params"), dict) else {}
        meta = params.get("_meta") if isinstance(params.get("_meta"), dict) else {}
        version = meta.get(CLE_VERSION) or self.version_poignee
        if version:
            h["MCP-Protocol-Version"] = str(version)
        if "method" in m:
            h["Mcp-Method"] = _valeur_entete(str(m["method"]))
            nom = params.get("name") or params.get("uri")
            if m["method"] in AVEC_NOM and isinstance(nom, str):
                h["Mcp-Name"] = _valeur_entete(nom)
        return h

    def relayer(self, ligne: str) -> list[dict]:
        try:
            m = json.loads(ligne)
        except json.JSONDecodeError:
            return [{"jsonrpc": "2.0", "id": None, "error": {"code": -32700, "message": "JSON illisible"}}]
        if not isinstance(m, dict):
            return [{"jsonrpc": "2.0", "id": None, "error": {"code": -32600, "message": "un message à la fois"}}]
        req = urllib.request.Request(self.url, data=json.dumps(m).encode(), headers=self.entetes(m), method="POST")
        try:
            with urllib.request.urlopen(req, timeout=60) as r:
                corps, sorte = r.read(), r.headers.get("Content-Type", "")
        except urllib.error.HTTPError as e:  # 4xx/5xx : on rend l'erreur JSON-RPC du central à la requête
            corps, sorte = e.read(), e.headers.get("Content-Type", "")
            if "id" not in m:
                return []
            try:
                err = json.loads(corps).get("error") or {}
            except (json.JSONDecodeError, AttributeError):
                err = {}
            return [
                {
                    "jsonrpc": "2.0",
                    "id": m["id"],
                    "error": {"code": err.get("code", -32000), "message": err.get("message") or f"HTTP {e.code}", **({"data": err["data"]} if "data" in err else {})},
                }
            ]
        except (urllib.error.URLError, TimeoutError) as e:
            return [{"jsonrpc": "2.0", "id": m["id"], "error": {"code": -32000, "message": f"central injoignable : {e}"}}] if "id" in m else []
        if not corps:
            return []  # notification acceptée (202)
        sortie = []
        if "text/event-stream" in sorte:
            for bloc in corps.decode().split("\n\n"):
                donnees = "\n".join(x[5:].lstrip() for x in bloc.splitlines() if x.startswith("data:"))
                if donnees:
                    sortie.append(json.loads(donnees))
        else:
            sortie.append(json.loads(corps))
        for x in sortie:  # mémorise la version négociée par la poignée de main
            if m.get("method") == "initialize" and isinstance(x.get("result"), dict):
                self.version_poignee = x["result"].get("protocolVersion")
        return sortie


def main() -> int:
    if len(sys.argv) != 2 or not os.environ.get("KANTAMA_MCP_JETON"):
        print("usage : KANTAMA_MCP_JETON=kmcp_… python pont_mcp.py URL_DU_POINT_MCP", file=sys.stderr)
        return 2
    pont = Pont(sys.argv[1], os.environ["KANTAMA_MCP_JETON"])
    # Octets UTF-8 des deux côtés (sous Windows, le texte de la console n'est pas UTF-8 par défaut).
    for brut in sys.stdin.buffer:
        ligne = brut.decode("utf-8", "replace")
        if not ligne.strip():
            continue
        for reponse in pont.relayer(ligne):
            sys.stdout.buffer.write(json.dumps(reponse, ensure_ascii=False).encode() + b"\n")
            sys.stdout.buffer.flush()
    return 0


if __name__ == "__main__":
    sys.exit(main())
OutilArgumentsRend
lister_projets—projets, agents, sondes, alertes, nombre d'actions
lister_agents—hôte, statut, version, empreinte, dernier battement
voir_projetprojetservices, sondes, certificats, actions déclarées
lister_deploiementsprojetversions en ligne, précédentes, derniers commits, prévisualisations
lister_alertesetat?, projet?100 alertes au plus
lister_erreursprojet, etat?50 erreurs au plus, masquées
lister_sauvegardesprojet?sauvegardes déclarées et 15 dernières opérations
lire_journaltype?, projet?, derniersévénements du journal chaîné (200 au plus)
lister_ordresstatut?, projet?, limiteordres et lien « relire et signer » des brouillons
voir_ordreordre_idparamètres et résultat lus dans les octets signés
preparer_ordreprojet, env, action, params?un brouillon, qui attend la passkey d'un humain

Webhook de l'espace

À chaque changement d'état d'une alerte, le central envoie un POST signé à votre adresse (en https://). Le détail des évènements est dans Alertes. Pour vérifier la signature :

verifier.py
import hashlib, hmac, time

def verifier(secret: str, entete: str, corps: bytes) -> bool:
    # Kantama-Signature: t=1794300012,v1=<hex>
    champs = dict(x.split("=", 1) for x in entete.split(","))
    if abs(time.time() - int(champs["t"])) > 300:
        return False
    attendu = hmac.new(secret.encode(), champs["t"].encode() + b"." + corps, hashlib.sha256).hexdigest()
    return hmac.compare_digest(attendu, champs["v1"])
Cette page vous a-t-elle aidé ?Modifier cette page

Les propositions de modification de la documentation ne sont pas encore ouvertes au public.