docs
fren clé sandbox

référence

référence des outils mcp

Un serveur MCP, deux profils. Une clé agent expose 5 outils agent ; une clé admin expose 12 outils admin. Chaque outil renvoie du JSON en contenu texte.

connexion

paramètrevaleur
point d'accèshttps://mcp.nostro.ag/mcp
transportStreamable HTTP, sans état (pas d'id de session), réponses JSON
authentificationAuthorization: Bearer <key>
en-têtescontent-type: application/json, accept: application/json, text/event-stream
servernostro v0.1.0

Les outils visibles dépendent de la clé : nst_ donne le profil agent, nsa_ le profil admin. Une mauvaise clé échoue au niveau HTTP avec 401 et le code JSON-RPC -32001. La configuration de Claude Code, Claude Desktop et Cursor est dans le démarrage rapide.

forme des réponses

Les résultats sont du contenu texte MCP contenant du JSON indenté. Les issues métier comme denied ou pending_approval sont des résultats normaux. Les échecs (introuvable, agent gelé, entrée invalide) reviennent avec isError: true :

erreur d'outil
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"error\": \"Agent gelé par l'entreprise : aucune dépense possible\"\n}"
      }
    ],
    "isError": true
  }
}
Consignes à l'agent Avec une clé agent, le serveur indique au modèle : appeler get_wallet avant toute dépense, respecter chaque décision, ne jamais fractionner un montant pour contourner le mandat.

outils agent

Limités à l'agent appelant : sa carte, son mandat, son activité.

get_wallet

clé agent nst_REST · GET /v1/agent/wallet

Budget restant (jour, mois), plafonds, statut de la carte et solde disponible du compte de l'entreprise. Les agents sont invités à l'appeler avant toute dépense.

Aucun paramètre.

requête · tools/call
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_wallet",
    "arguments": {}
  }
}
résultat (dans content[0].text)
{
  "agent": {
    "id": "agt_3f2b8d10",
    "name": "demo-agent",
    "status": "active"
  },
  "card": {
    "id": "vcard_5e1d77a0c4b2",
    "maskedNumber": "4970 •••• •••• 3182",
    "status": "Enabled"
  },
  "accountAvailable": {
    "value": "10000.00",
    "currency": "EUR"
  },
  "budget": {
    "currency": "EUR",
    "perTxMax": 500,
    "approvalAbove": 250,
    "dailyRemaining": 2000,
    "monthlyRemaining": 5000
  },
  "transfersEnabled": false
}

pay

clé agent nst_REST · POST /v1/agent/pay

Paie un marchand avec la carte virtuelle de l'agent. Évalué d'abord contre le mandat : exécuté, bloqué ou mis en attente d'approbation humaine.

nomtypedescription
amountnumberrequisMontant en euros, > 0. Arrondi à 2 décimales, ex. 19.99.
merchantstringrequisNom du marchand. Comparé à blockedMerchants.
mccstringoptionnelCode catégorie marchand, exactement 4 chiffres, ex. 5734. Obligatoire si le mandat a des allowedMccs.
descriptionstringoptionnelObjet de la dépense. Enregistré dans le journal d'audit.
requête · tools/call
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "pay",
    "arguments": {
      "amount": 49,
      "merchant": "Vercel",
      "mcc": "5734",
      "description": "Pro plan, November"
    }
  }
}
résultat · paid (dans content[0].text)
{
  "status": "paid",
  "transactionId": "vtx_883b5610e2a1",
  "amount": 49,
  "merchant": "Vercel"
}
résultat · pending_approval
{
  "status": "pending_approval",
  "requestId": "req_ef5c846c",
  "reason": "Au-dessus du seuil d'approbation (250 €)",
  "message": "Demande transmise à un humain de l'entreprise. Vérifie son statut avec get_request_status."
}
résultat · denied
{
  "status": "denied",
  "reason": "Dépasse le plafond par transaction (500 €)"
}
résultat · declined_by_bank
{
  "status": "declined_by_bank",
  "reason": "InsufficientFunds"
}

send_transfer

clé agent nst_REST · POST /v1/agent/transfer

Envoie un virement SEPA depuis le compte de l'entreprise, uniquement si le mandat autorise les virements. Le plus souvent soumis à approbation humaine.

nomtypedescription
amountnumberrequisMontant en euros, > 0.
ibanstringrequisIBAN du bénéficiaire. Espaces retirés ; doit respecter ^[A-Z]{2}\d{2}[A-Z0-9]{10,30}$.
beneficiaryNamestringrequisNom du bénéficiaire.
labelstringoptionnelLibellé, 140 caractères max. Par défaut « Nostro <nom de l'agent> ».
requête · tools/call
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "send_transfer",
    "arguments": {
      "amount": 1200,
      "iban": "FR7630006000011234567890189",
      "beneficiaryName": "Acme SAS",
      "label": "Invoice 2026-114"
    }
  }
}
résultat · pending_approval (dans content[0].text)
{
  "status": "pending_approval",
  "requestId": "req_51c0aa9e",
  "reason": "Virement soumis à approbation humaine",
  "message": "Demande transmise à un humain de l'entreprise. Vérifie son statut avec get_request_status."
}
résultat · initiated
{
  "status": "initiated",
  "paymentId": "vpay_9d21c4e07a11",
  "bankStatus": "Initiated"
}
résultat · denied
{
  "status": "denied",
  "reason": "Virements désactivés pour cet agent"
}

list_my_activity

clé agent nst_REST · GET /v1/agent/activity

Historique propre à l'agent : chaque paiement, virement et décision (exécuté, refusé, en attente). Du plus récent au plus ancien.

nomtypedescription
limitintegeroptionnel1 à 100, 20 par défaut. (Le REST renvoie les 50 derniers.)
requête · tools/call
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_my_activity",
    "arguments": {
      "limit": 2
    }
  }
}
résultat (dans content[0].text)
[
  {
    "id": 7,
    "workspace_id": "ws_7c1e9a42b0d3",
    "agent_id": "agt_3f2b8d10",
    "type": "card_payment",
    "amount": 320,
    "counterparty": "AWS",
    "decision": "executed",
    "reason": null,
    "bank_ref": "vtx_acf5376d09be",
    "created_at": "2026-11-05T09:20:41.560Z",
    "agent_name": "demo-agent"
  },
  {
    "id": 5,
    "workspace_id": "ws_7c1e9a42b0d3",
    "agent_id": "agt_3f2b8d10",
    "type": "card_payment",
    "amount": 900,
    "counterparty": "Apple",
    "decision": "denied",
    "reason": "Dépasse le plafond par transaction (500 €)",
    "bank_ref": null,
    "created_at": "2026-11-05T09:18:02.491Z",
    "agent_name": "demo-agent"
  }
]

get_request_status

clé agent nst_REST · GET /v1/agent/requests/:id

Statut d'une dépense en attente d'approbation humaine. Un agent ne lit que ses propres demandes.

nomtypedescription
requestIdstringrequisL'identifiant req_... renvoyé par pay ou send_transfer.
requête · tools/call
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_request_status",
    "arguments": {
      "requestId": "req_ef5c846c"
    }
  }
}
résultat (dans content[0].text)
{
  "id": "req_ef5c846c",
  "kind": "card_payment",
  "amount": 320,
  "status": "executed",
  "reason": "Au-dessus du seuil d'approbation (250 €)",
  "result": {
    "amount": 320,
    "status": "paid",
    "merchant": "AWS",
    "transactionId": "vtx_acf5376d09be"
  },
  "createdAt": "2026-11-05T09:19:33.478Z",
  "decidedAt": "2026-11-05T09:20:41.561Z"
}

outils admin

Limités à l'espace de la clé admin. Réservez-les aux humains, ou à un agent opérateur supervisé à qui vous confiez tout le budget.

overview

clé admin nsa_REST · GET /api/overview

Compte, solde, nombre d'agents actifs, approbations en attente et dépenses du mois.

Aucun paramètre.

requête · tools/call
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "overview",
    "arguments": {}
  }
}
résultat (dans content[0].text)
{
  "workspace": {
    "id": "ws_7c1e9a42b0d3",
    "name": "Acme",
    "kind": "sandbox",
    "account_id": "vacc_2b9d01e6f3a8",
    "created_at": "2026-11-05T09:12:03.870Z"
  },
  "bankMode": "ledger",
  "account": {
    "id": "vacc_2b9d01e6f3a8",
    "name": "Acme",
    "iban": "FR7699999481207365519024618",
    "status": "Opened",
    "available": {
      "value": "9631.00",
      "currency": "EUR"
    },
    "booked": {
      "value": "9631.00",
      "currency": "EUR"
    }
  },
  "agents": 1,
  "pendingApprovals": 0,
  "monthSpend": 369,
  "swanConfigured": false,
  "swanUserId": null
}

list_agents

clé admin nsa_REST · GET /api/agents

Tous les agents non révoqués avec carte, mandat et dépenses en cours.

Aucun paramètre.

requête · tools/call
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_agents",
    "arguments": {}
  }
}
résultat (dans content[0].text)
[
  {
    "id": "agt_3f2b8d10",
    "name": "demo-agent",
    "purpose": "Demo agent (sandbox, fake euros)",
    "status": "active",
    "keyPrefix": "nst_k3Jd",
    "card": {
      "id": "vcard_5e1d77a0c4b2",
      "status": "Enabled",
      "maskedNumber": "4970 •••• •••• 3182",
      "consentUrl": null
    },
    "policy": {
      "currency": "EUR",
      "perTxMax": 500,
      "dailyMax": 2000,
      "monthlyMax": 5000,
      "approvalAbove": 250,
      "allowedMccs": [],
      "blockedMerchants": [],
      "transfersEnabled": false,
      "transferApprovalAbove": 0
    },
    "spend": {
      "today": 49,
      "month": 49
    },
    "createdAt": "2026-11-05T09:12:04.118Z"
  }
]

create_agent

clé admin nsa_REST · POST /api/agents

Crée un agent avec sa carte virtuelle au nom de l'entreprise, son mandat et sa clé API. La clé n'est renvoyée qu'une seule fois.

nomtypedescription
namestringrequisNom de l'agent, repris dans le libellé de la carte.
purposestringoptionnelTexte libre : à quoi sert cet agent.
perTxMaxnumberoptionnelMontant maximum d'un paiement carte, en euros. Au-delà, le paiement est bloqué.
dailyMaxnumberoptionnelDépense exécutée maximum par jour calendaire (UTC), paiements carte et virements cumulés.
monthlyMaxnumberoptionnelBudget mensuel. Également posé comme plafond de dépense sur la carte elle-même (défense en profondeur).
approvalAbovenumberoptionnelLes paiements carte strictement au-dessus de ce montant attendent une approbation humaine au lieu d'être exécutés.
allowedMccsstring[]optionnelCodes catégorie marchand (MCC, 4 chiffres) autorisés. Vide signifie toutes les catégories.
blockedMerchantsstring[]optionnelMarchands à bloquer. Correspondance partielle, insensible à la casse, sur le nom du marchand.
transfersEnabledbooleanoptionnelAutorise ou non l'agent à envoyer des virements SEPA.
transferApprovalAbovenumberoptionnelLes virements strictement au-dessus de ce montant demandent une approbation humaine. 0 signifie que tout virement est revu.
requête · tools/call
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_agent",
    "arguments": {
      "name": "procurement-bot",
      "purpose": "Buys SaaS seats",
      "perTxMax": 200,
      "dailyMax": 600,
      "monthlyMax": 3000,
      "approvalAbove": 100,
      "allowedMccs": [
        "5734",
        "7372"
      ]
    }
  }
}
résultat (dans content[0].text)
{
  "agent": {
    "id": "agt_91ad04c2",
    "name": "procurement-bot",
    "purpose": "Buys SaaS seats",
    "status": "active",
    "keyPrefix": "nst_Qm7v",
    "card": {
      "id": "vcard_0c44e1b9a7d0",
      "status": "Enabled",
      "maskedNumber": "4970 •••• •••• 7745",
      "consentUrl": null
    },
    "policy": {
      "currency": "EUR",
      "perTxMax": 200,
      "dailyMax": 600,
      "monthlyMax": 3000,
      "approvalAbove": 100,
      "allowedMccs": [
        "5734",
        "7372"
      ],
      "blockedMerchants": [],
      "transfersEnabled": false,
      "transferApprovalAbove": 0
    },
    "spend": {
      "today": 0,
      "month": 0
    },
    "createdAt": "2026-11-05T09:12:04.118Z"
  },
  "apiKey": "nst_Qm7v••••••••••••••••••••••••"
}

update_agent_policy

clé admin nsa_REST · POST /api/agents/:id/policy

Modifie le mandat d'un agent. Seuls les champs envoyés changent, le reste est conservé. Modifier monthlyMax met aussi à jour le plafond de la carte.

nomtypedescription
agentIdstringrequisL'identifiant agt_....
perTxMaxnumberoptionnelMontant maximum d'un paiement carte, en euros. Au-delà, le paiement est bloqué.
dailyMaxnumberoptionnelDépense exécutée maximum par jour calendaire (UTC), paiements carte et virements cumulés.
monthlyMaxnumberoptionnelBudget mensuel. Également posé comme plafond de dépense sur la carte elle-même (défense en profondeur).
approvalAbovenumberoptionnelLes paiements carte strictement au-dessus de ce montant attendent une approbation humaine au lieu d'être exécutés.
allowedMccsstring[]optionnelCodes catégorie marchand (MCC, 4 chiffres) autorisés. Vide signifie toutes les catégories.
blockedMerchantsstring[]optionnelMarchands à bloquer. Correspondance partielle, insensible à la casse, sur le nom du marchand.
transfersEnabledbooleanoptionnelAutorise ou non l'agent à envoyer des virements SEPA.
transferApprovalAbovenumberoptionnelLes virements strictement au-dessus de ce montant demandent une approbation humaine. 0 signifie que tout virement est revu.
requête · tools/call
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "update_agent_policy",
    "arguments": {
      "agentId": "agt_3f2b8d10",
      "approvalAbove": 100,
      "blockedMerchants": [
        "casino",
        "crypto"
      ]
    }
  }
}
résultat (dans content[0].text)
{
  "id": "agt_3f2b8d10",
  "name": "demo-agent",
  "purpose": "Demo agent (sandbox, fake euros)",
  "status": "active",
  "keyPrefix": "nst_k3Jd",
  "card": {
    "id": "vcard_5e1d77a0c4b2",
    "status": "Enabled",
    "maskedNumber": "4970 •••• •••• 3182",
    "consentUrl": null
  },
  "policy": {
    "currency": "EUR",
    "perTxMax": 500,
    "dailyMax": 2000,
    "monthlyMax": 5000,
    "approvalAbove": 100,
    "allowedMccs": [],
    "blockedMerchants": [
      "casino",
      "crypto"
    ],
    "transfersEnabled": false,
    "transferApprovalAbove": 0
  },
  "spend": {
    "today": 49,
    "month": 49
  },
  "createdAt": "2026-11-05T09:12:04.118Z"
}

freeze_agent

clé admin nsa_REST · POST /api/agents/:id/freeze

Coupe-circuit : bloque immédiatement toute dépense de l'agent. Réversible.

nomtypedescription
agentIdstringrequisL'identifiant agt_....
requête · tools/call
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "freeze_agent",
    "arguments": {
      "agentId": "agt_3f2b8d10"
    }
  }
}
résultat (dans content[0].text)
{
  "id": "agt_3f2b8d10",
  "name": "demo-agent",
  "purpose": "Demo agent (sandbox, fake euros)",
  "status": "frozen",
  "keyPrefix": "nst_k3Jd",
  "card": {
    "id": "vcard_5e1d77a0c4b2",
    "status": "Enabled",
    "maskedNumber": "4970 •••• •••• 3182",
    "consentUrl": null
  },
  "policy": {
    "currency": "EUR",
    "perTxMax": 500,
    "dailyMax": 2000,
    "monthlyMax": 5000,
    "approvalAbove": 250,
    "allowedMccs": [],
    "blockedMerchants": [],
    "transfersEnabled": false,
    "transferApprovalAbove": 0
  },
  "spend": {
    "today": 49,
    "month": 49
  },
  "createdAt": "2026-11-05T09:12:04.118Z"
}

unfreeze_agent

clé admin nsa_REST · POST /api/agents/:id/unfreeze

Réactive un agent gelé.

nomtypedescription
agentIdstringrequisL'identifiant agt_....
requête · tools/call
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "unfreeze_agent",
    "arguments": {
      "agentId": "agt_3f2b8d10"
    }
  }
}
résultat (dans content[0].text)
{
  "id": "agt_3f2b8d10",
  "name": "demo-agent",
  "purpose": "Demo agent (sandbox, fake euros)",
  "status": "active",
  "keyPrefix": "nst_k3Jd",
  "card": {
    "id": "vcard_5e1d77a0c4b2",
    "status": "Enabled",
    "maskedNumber": "4970 •••• •••• 3182",
    "consentUrl": null
  },
  "policy": {
    "currency": "EUR",
    "perTxMax": 500,
    "dailyMax": 2000,
    "monthlyMax": 5000,
    "approvalAbove": 250,
    "allowedMccs": [],
    "blockedMerchants": [],
    "transfersEnabled": false,
    "transferApprovalAbove": 0
  },
  "spend": {
    "today": 49,
    "month": 49
  },
  "createdAt": "2026-11-05T09:12:04.118Z"
}

revoke_agent

clé admin nsa_REST · POST /api/agents/:id/revoke

Révoque la clé de l'agent et annule sa carte. Irréversible.

nomtypedescription
agentIdstringrequisL'identifiant agt_....
requête · tools/call
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "revoke_agent",
    "arguments": {
      "agentId": "agt_3f2b8d10"
    }
  }
}
résultat (dans content[0].text)
{
  "ok": true
}

list_pending_approvals

clé admin nsa_REST · GET /api/requests?status=pending

Dépenses en attente d'une décision humaine, des plus récentes aux plus anciennes (100 max).

Aucun paramètre.

requête · tools/call
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_pending_approvals",
    "arguments": {}
  }
}
résultat (dans content[0].text)
[
  {
    "id": "req_ef5c846c",
    "agent_id": "agt_3f2b8d10",
    "kind": "card_payment",
    "amount": 320,
    "payload": {
      "amount": 320,
      "merchant": "AWS",
      "mcc": "7372"
    },
    "reason": "Au-dessus du seuil d'approbation (250 €)",
    "status": "pending",
    "result": null,
    "created_at": "2026-11-05T09:19:33.478Z",
    "decided_at": null,
    "agent_name": "demo-agent"
  }
]

approve_request

clé admin nsa_REST · POST /api/requests/:id/approve

Approuve une demande en attente et l'exécute immédiatement. Une seule décision par demande, même en cas de clics simultanés.

nomtypedescription
requestIdstringrequisL'identifiant req_....
requête · tools/call
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "approve_request",
    "arguments": {
      "requestId": "req_ef5c846c"
    }
  }
}
résultat (dans content[0].text)
{
  "id": "req_ef5c846c",
  "kind": "card_payment",
  "amount": 320,
  "status": "executed",
  "reason": "Au-dessus du seuil d'approbation (250 €)",
  "result": {
    "amount": 320,
    "status": "paid",
    "merchant": "AWS",
    "transactionId": "vtx_acf5376d09be"
  },
  "createdAt": "2026-11-05T09:19:33.478Z",
  "decidedAt": "2026-11-05T09:20:41.561Z"
}

reject_request

clé admin nsa_REST · POST /api/requests/:id/reject

Refuse une demande en attente. Rien n'est débité.

nomtypedescription
requestIdstringrequisL'identifiant req_....
requête · tools/call
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "reject_request",
    "arguments": {
      "requestId": "req_51c0aa9e"
    }
  }
}
résultat (dans content[0].text)
{
  "id": "req_51c0aa9e",
  "kind": "transfer",
  "amount": 1200,
  "status": "rejected",
  "reason": "Virement soumis à approbation humaine",
  "result": null,
  "createdAt": "2026-11-05T09:22:10.002Z",
  "decidedAt": "2026-11-05T09:25:47.310Z"
}

fund_account

clé admin nsa_REST · POST /api/fund

Sandbox uniquement : crédite le registre virtuel de l'espace (virement SEPA entrant simulé, euros fictifs).

nomtypedescription
amountnumberrequisEuros, > 0 et ≤ 100 000 par appel. Un solde sandbox est plafonné à 1 000 000.
requête · tools/call
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "fund_account",
    "arguments": {
      "amount": 5000
    }
  }
}
résultat (dans content[0].text)
{
  "transactionId": "vtx_c7b3a7331f0c"
}

audit_log

clé admin nsa_REST · GET /api/events?agentId=&limit=

Toutes les décisions et opérations de l'espace, des plus récentes aux plus anciennes, éventuellement pour un seul agent.

nomtypedescription
agentIdstringoptionnelFiltrer sur un agent.
limitintegeroptionnel1 à 500, 100 par défaut.
requête · tools/call
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "audit_log",
    "arguments": {
      "agentId": "agt_3f2b8d10",
      "limit": 3
    }
  }
}
résultat (dans content[0].text)
[
  {
    "id": 7,
    "workspace_id": "ws_7c1e9a42b0d3",
    "agent_id": "agt_3f2b8d10",
    "type": "card_payment",
    "amount": 320,
    "counterparty": "AWS",
    "decision": "executed",
    "reason": null,
    "bank_ref": "vtx_acf5376d09be",
    "created_at": "2026-11-05T09:20:41.560Z",
    "agent_name": "demo-agent"
  },
  {
    "id": 4,
    "workspace_id": "ws_7c1e9a42b0d3",
    "agent_id": "agt_3f2b8d10",
    "type": "card_payment",
    "amount": 320,
    "counterparty": "AWS",
    "decision": "pending_approval",
    "reason": "Au-dessus du seuil d'approbation (250 €)",
    "bank_ref": "req_ef5c846c",
    "created_at": "2026-11-05T09:19:33.480Z",
    "agent_name": "demo-agent"
  },
  {
    "id": 2,
    "workspace_id": "ws_7c1e9a42b0d3",
    "agent_id": "agt_3f2b8d10",
    "type": "agent_created",
    "amount": null,
    "counterparty": null,
    "decision": "executed",
    "reason": "Carte 4970 •••• •••• 3182 (Enabled)",
    "bank_ref": "vcard_5e1d77a0c4b2",
    "created_at": "2026-11-05T09:12:04.120Z",
    "agent_name": "demo-agent"
  }
]