Référence des outils

Le serveur Maetra MCP expose un ensemble d'outils dépendant des capacités. Appeler tools/list pour découvrir les outils disponibles dans l'espace de travail actuel et la clé API.

Invoquer un outil avec tools/call:

{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {
    "name": "check_task_alignment",
    "arguments": {
      "mcp_access_token": "<token from get_mcp_access>",
      "session_ref": "conversation_01JY8Q",
      "action": "Edit the refund approval route"
    }
  }
}

Accès avant le vol#

Obtenir\ mcp\ accès

Appel obligatoire pour chaque nouveau tour d'utilisateur ou cycle de travail, après compactage ou redémarrage du contexte, et chaque fois qu'Maetra demande un rafraîchissement d'accès. Pas d'argument.

La réponse contient:

Champ	Désignation des marchandises
`workspace`	L'ID de l'espace de travail, l'état d'MCP activé et la version de configuration.
`capabilities`	Activer l'état, la raison et permettre des outils pour Secure, Govern et Task Guard.
`required_behavior`	Instructions d'exécution que l'hôte doit suivre.
`mcp_access_token`	Jeton de courte durée requis par chaque outil de capacité.
`expires_at`	L'expiration de la marque d'accès.

{
  "name": "get_mcp_access",
  "arguments": {}
}

Remarque Chaque outil ci-dessous nécessite un argument de chaîne supplémentaire, mcp_access_token, contenant le jeton actuel retourné par get_mcp_access.

Outils Task Guard#

tâche de démarrage

Démarrer ou passer à la tâche Task Guard actuellement autorisée par l'utilisateur.

Argument	Type	Requis	Désignation des marchandises
`session_ref`	chaîne de caractères	✓	Conversation d'hôte stable ou référence de session.
`objective`	chaîne de caractères	✓	L'objectif actuel de l'utilisateur direct.
`idempotency_key`	chaîne de caractères	✓	Clé stable de réessayer pour le début de la tâche.
`title`	chaîne de caractères		Titre de la tâche courte.
`agent_name` / `agent_id`	chaîne de caractères		Identité de l'agent.
`constraints`, `decisions`	chaîne[]		Contraintes de l'utilisateur et décisions convenues.
`success_criteria`	chaîne[]		Conditions d'achèvement observables.
`in_scope`, `out_of_scope`	chaîne[]		Limites explicites des tâches.
`open_questions`	chaîne[]		Questions non résolues.
`direct_user_event_id`	chaîne de caractères		Requis pour une tâche ultérieure ou une révision du contrat à la même session.
`host_type`	chaîne de caractères		`CODEX`, `CLAUDE`, `CUSTOM_MCP`ou `CUSTOM_API`.
`integration_mode`	chaîne de caractères		`ADVISORY` ou `ENFORCED`.
`confirmation_capable`	booléen		Indique si l'hôte peut demander à l'utilisateur de la session en ligne.
`effect_reporting_capable`	booléen		Indique si l'hôte peut signaler les effets réels.

Après le début, conserver task.id, contract_version, et l'ancre retournée.

get\ task\ context

Récupérer le contrat Task Guard actif après le début du virage, le compactage, le redémarrage ou quand le contexte peut être inexistant.

Argument	Type	Requis
`session_ref`	chaîne de caractères	✓

vérifier\ task\ alignement

Vérifiez une action matérielle proposée contre la tâche active avant de l'exécuter.

Argument	Type	Requis	Désignation des marchandises
`session_ref`	chaîne de caractères	✓	Référence stable pour la session.
`action`	chaîne de caractères	✓	Mesures concrètes proposées.
`action_type`	chaîne de caractères		Catégorie telle que `edit`, `read`, `send`, `create`ou `execute`.
`target`	chaîne de caractères		Fichier, système, personne, artefact ou autre cible.
`effects`	chaîne[]		Effets directs et liés attendus.
`rationale`	chaîne de caractères		Pourquoi l'action soutient la tâche.
`current_step`	chaîne de caractères		Étape actuelle de la tâche.
`contract_version`	Numéro		Dernière version du contrat récupérée par l'hôte.
`external_action_id`	chaîne de caractères		ID d'action de l'hôte stable utilisé pour lier les rapports d'effet.
`idempotency_key`	chaîne de caractères		Clé stable de réessayer.
`effect`	chaîne de caractères		`READ`, `SEARCH`, `CREATE`, `MODIFY`, `DELETE`, `COMMUNICATE`, `PUBLISH`, `EXECUTE`, `PURCHASE`, `TRANSFER`, `GRANT_ACCESS`, `REVOKE_ACCESS`, `MOVE_DATA`, `SCHEDULE`ou `OTHER`.
`tool_name`, `operation`	chaîne de caractères		Outil et fonctionnement en cours de vérification.
`resource`, `destination`	objet		Métadonnées structurées des cibles et des destinations.
`data_classes`	chaîne[]		Classification des données concernées.
`reversible`	booléen		Si l'action peut être annulée.
`estimated_cost`	Numéro		Coût monétaire estimé.
`provenance`	chaîne de caractères		`HOST_VERIFIED`, `TOOL_ADAPTER_VERIFIED`, `CONNECTOR_VERIFIED`, `AGENT_ASSERTED`ou `UNVERIFIED`.
`claimed_relationship`	chaîne de caractères		Comment l'action soutient la tâche: `DIRECT`, `REQUIRED_DEPENDENCY`, `COMPATIBILITY_REPAIR`, `VERIFICATION`, `SUPPORTING_RESEARCH`, `SUPPORTING_COORDINATION`, `INCIDENTAL_CLEANUP`, `OPTIONAL_IMPROVEMENT`, `OBJECTIVE_CHANGE`, `UNRELATED`ou `UNKNOWN`.

Suivre le retour verdict et next_action Exactement. Voir Jugements d'alignement.

Expliquez la relation tâche

Fournir des preuves limitées lorsque check_task_alignment retours NEEDS_EXPLANATION.

Argument	Type	Requis
`check_id`	chaîne de caractères	✓
`relationship`	chaîne de caractères	✓
`evidence`	chaîne[]

La réponse est une nouvelle décision d'alignement. Suivez son verdict.

enregistrement\ task\ progress

Consigner un jalon compact pour la tâche active.

Argument	Type	Requis
`session_ref`	chaîne de caractères	✓
`summary`	chaîne de caractères	✓
`idempotency_key`	chaîne de caractères	✓
`completed`, `next_steps`	chaîne[]
`new_dependencies`, `open_questions`	chaîne[]
`current_step`	chaîne de caractères

Vérifiez chaque new_dependencies article avec check_task_alignment avant d'agir dessus.

enregistrement\ action\ effet

Signalez ce qu'une action précédemment vérifiée a réellement changé.

Argument	Type	Requis
`check_id`	chaîne de caractères	✓
`actual_effects`	chaîne[]	✓
`actual_effect`	chaîne de caractères
`affected_resources`	objet[]
`result_reference`, `artifact_hash`	chaîne de caractères
`summary`, `validation_outcome`	chaîne de caractères

Si effect_aligned est faux, arrêtez d'élargir le travail et demandez à l'utilisateur de session en ligne.

Tâche complète

Achever la tâche active d'Task Guard lorsque l'objectif et les critères de succès sont satisfaits.

Argument	Type	Requis
`session_ref`	chaîne de caractères	✓
`summary`	chaîne de caractères	✓
`completion_event_id`	chaîne de caractères	✓

Outils Secure#

vérifier\ action

Scanner une prompte AI-agent, un appel d'outil, ou une sortie avec Maetra Secure. Dos POST /v1/secure/scan.

Argument	Type	Requis	Désignation des marchandises
`content`	chaîne de caractères	✓	Prompt, charge utile de l'outil, ou sortie pour scanner.
`scan_type`	chaîne de caractères		`prompt_input` (par défaut), `tool_call`ou `output`.
`tool_name`	chaîne de caractères	✓ si `tool_call`	L'outil est appelé.
`agent_id`, `agent_name`	chaîne de caractères		Identité de l'agent.
`context`	objet		Contexte structuré.

Honoraires safe, flaggedou bloqué avant de continuer.

list\ active\ rules

Lister les règles actives d'Secure. Pas d'arguments au-delà mcp_access_token.

créer\ règle

Créez une règle Secure. Nouvelles règles par défaut à draft.

Argument	Type	Requis	Désignation des marchandises
`name`	chaîne de caractères	✓	Nom de la règle.
`type`	chaîne de caractères	✓	`data_pattern`, `policy_dsl`, `prompt_pattern`ou `tool_call`.
`action`	chaîne de caractères		`block`, `flag`ou `log`.
`severity`	chaîne de caractères		`critical`, `high`, `medium`ou `low`.
`status`	chaîne de caractères		`active`, `archived`ou `draft`.
`applies_to_all`	booléen		Par défaut à `true`.
`data_direction`	chaîne de caractères		`inbound`, `outbound`ou `both`.
`custom_patterns`, `tool_names`, `data_categories`, `data_descriptions`, `dsl_statements`, `pattern_library_ids`, `agent_ids`	chaîne[]		Valeurs spécifiques aux règles.

update\ rule

Mettre à jour une règle Secure existante par ID. id est nécessaire ; chaque champ create-rule est facultatif et ne change que les champs soumis.

Outils Govern#

demande d'approbation

Demander un point de contrôle Govern avant une action en conséquence. Dos POST /v1/checkpoints.

Argument	Type	Requis	Désignation des marchandises
`action`	chaîne de caractères	✓	Nom d'action.
`payload`	objet		Détails d'action structurés.
`agent_id`, `agent_name`	chaîne de caractères		Identité de l'agent.
`context`, `reasoning`	chaîne de caractères		Contexte de l'examinateur et raisonnement de l'agent.
`autonomy_level`	chaîne de caractères		`L0`–`L5`.
`policy_ids`, `policy_group_ids`	chaîne[]		Restreindre l'évaluation.
`timeout_seconds`	Numéro		Plafond horaire pour une décision humaine.
`idempotency_key`	chaîne de caractères		La clé de réessayer stable pour créer le point de contrôle.
`target`	objet		Compte exact, ressource, destination ou système externe. Obligatoire pour l'autorisation d'exécution.
`task_authorization`	objet		Autorité chargée de la tâche `task_id`, `revision_id`et `external_action_id`C'est vrai. Obligatoire pour l'autorisation d'exécution.
`runtime`	objet		Outil en version ou identité de modèle. Obligatoire pour l'autorisation d'exécution.
`executor_audience`	chaîne de caractères		Identité de l'exécuteur-exécuteur. Par défaut à `maetra-executor`.

Si la réponse est en attente, continuer le scrutin avec get_approval_statusC'est vrai. Une réponse approuvée est la décision; appel authorize_execution immédiatement avant l'action externe pour consommer cette approbation une fois.

La réponse approuvée comprend la réponse signée decisionToken, canonique actionEnvelope, actionEnvelopeHash, policyDigest, exact policyVersions, les chronomètres du cycle de vie en jeton, ainsi que les échéances d'exécution et d'exécution prévues. Maetra porte ces champs dans les outils d'exécution MCP automatiquement lorsque vous fournissez l'identifiant de point de contrôle.

get\ accept\ status

Long-poll un point de contrôle Govern.

Argument	Type	Requis
`checkpoint_id`	chaîne de caractères	✓
`wait_seconds`	Numéro

Sondage jusqu'à approuvé, rejected, expired, bloquéou cancelled.

liste\ active\ politiques

Lister les politiques actives d'Govern, y compris si chacune utilise des règles précises ou des renseignements de décision. Pas d'arguments au-delà mcp_access_token.

autorisation\ exécution

Consommez une capacité de décision approuvée une fois, immédiatement avant la demande exacte du fournisseur. Maetra recharge le poste de contrôle, vérifie sa décision signée et son enveloppe d'action canonique, et crée un reçu d'exécution signé.

Argument	Type	Requis	Désignation des marchandises
`checkpoint_id`	chaîne de caractères	✓	Points de contrôle approuvés retournés par `request_approval`.
`idempotency_key`	chaîne de caractères	✓	Clé stable pour cette exécution exacte. Une réessayer identique renvoie l'autorisation existante.
`provider`	chaîne de caractères	✓	Fournisseur externe ou système recevant la demande.
`operation`	chaîne de caractères	✓	L'exploitation des fournisseurs, comme `refunds.create`.
`request`	JSON	✓	Demande en aval normalisée qui sera envoyée après autorisation.

N'appelez pas le fournisseur d'abord. Une demande modifiée, un exécuteur testamentaire erroné, une décision expirée ou révoquée, ou une deuxième utilisation indépendante échoue. Les rappels de fournisseurs restent possibles sous le retour executionId.

enregistrement\ exécution\ tempt

Ajouter un fournisseur immuable à l'exécution autorisée. Consigner les succès, les échecs, les chronométrages et les rappels contre les mêmes execution_id.

Argument	Type	Requis	Désignation des marchandises
`execution_id`	chaîne de caractères	✓	ID retourné par `authorize_execution`.
`attempt_number`	Numéro	✓	Séquence de tentative positive, en commençant par `1`.
`request`	JSON	✓	Demande envoyée pour cette tentative de fournisseur.
`response`	JSON		Réponse du fournisseur, lorsque disponible.
`status`	chaîne de caractères	✓	`succeeded`, `failed`ou `unknown`.
`started_at`	chaîne de caractères	✓	L'heure de départ du fournisseur ISO 8601.
`completed_at`	chaîne de caractères		Temps d'achèvement de la norme ISO 8601, s'il est connu.
`provider_status`, `provider_transaction_id`, `error_class`	chaîne de caractères		Détails de rapprochement des fournisseurs.

Une tentative ratée ou inconnue ne consomme pas une autre décision. Réessayez seulement l'action autorisée identique, puis enregistrez le numéro de la prochaine tentative.

enregistrement\ exécution\ effet

Ajouter l'état observé après exécution. Cela relie l'action approuvée et la tentative du fournisseur à ce qui a réellement changé.

Argument	Type	Requis	Désignation des marchandises
`execution_id`	chaîne de caractères	✓	L'exécution autorisée est vérifiée.
`observation`	JSON	✓	État externe observé après exécution.
`observed_at`	chaîne de caractères	✓	Temps d'observation ISO 8601.
`verification_method`	chaîne de caractères	✓	`provider_signed`, `ledger_readback`, `hardware_attested`, `stake_backed`, `task_guard`ou `self_reported`.
`verification_status`	chaîne de caractères		`verified`, `mismatch`ou `unverified`; par défaut à `unverified`.
`proof`	JSON		Preuve spécifique à la méthode.
`provider`, `external_reference`, `task_guard_effect_report_id`	chaîne de caractères		Liens de réconciliation.

Les observations autodéclarées restent étiquetées unverifiedC'est vrai. Les méthodes de vérification indépendantes exigent que leur vérificateur configuré valide la preuve; l'appelant ne peut pas transformer une observation non vérifiée en un reçu vérifié en réglant un booléen.

Commande de commandes multiples#

Pour la même action matérielle:

Appeler check_task_alignment quand Task Guard est activée.
Appeler check_action avant de traiter du contenu non fiable ou d'exécuter l'appel à l'outil.
Appeler request_approval avant l'action extérieure quand Govern est activée.
Sondage jusqu'à ce que la décision soit finale; arrêt à moins qu'elle ne soit approuvée.
Appeler authorize_execution immédiatement avant la demande exacte du fournisseur.
Exécuter seulement après le succès de l'autorisation, puis appeler record_execution_attempt pour chaque tentative de fournisseur.
Appeler record_execution_effect avec l'état observé résultant.
Appeler record_action_effect lorsque la déclaration de l'effet Task Guard est activée.

La confirmation en ligne d'Task Guard ne remplace pas l'approbation de Govern, et l'approbation de Govern ne remplace pas l'autorisation d'exécution à usage unique.