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.
Les points sans session
| Point | Sert à | Accès |
|---|---|---|
GET /v1/sante | Savoir 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 /mcp | Le 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.
{"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.
# 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>/failErreurs 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.
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/mcpLe pont pont_mcp.py n'utilise que la bibliothèque standard de Python 3.10 ou plus : copiez-le tel quel.
"""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())| Outil | Arguments | Rend |
|---|---|---|
lister_projets | — | projets, agents, sondes, alertes, nombre d'actions |
lister_agents | — | hôte, statut, version, empreinte, dernier battement |
voir_projet | projet | services, sondes, certificats, actions déclarées |
lister_deploiements | projet | versions en ligne, précédentes, derniers commits, prévisualisations |
lister_alertes | etat?, projet? | 100 alertes au plus |
lister_erreurs | projet, etat? | 50 erreurs au plus, masquées |
lister_sauvegardes | projet? | sauvegardes déclarées et 15 dernières opérations |
lire_journal | type?, projet?, derniers | événements du journal chaîné (200 au plus) |
lister_ordres | statut?, projet?, limite | ordres et lien « relire et signer » des brouillons |
voir_ordre | ordre_id | paramètres et résultat lus dans les octets signés |
preparer_ordre | projet, 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 :
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"])Les propositions de modification de la documentation ne sont pas encore ouvertes au public.