MCP

Réponse directe

Chemins d’accès, étendues, wrappers d’exécution et contrôles d’exécution MCP actuels.

Contenu source

# MCP

TextTree expose une surface MCP délimitée pour la découverte et l'exécution contrôlée des outils.

## Itinéraires de base

-`GET /mcp/health`
-`POST /mcp`
-`POST /mcp/accounts`
-`GET /mcp/tools`
-`POST /mcp/tools/:name`
-`GET /api/v1/mcp/oauth-clients`
-`DELETE /api/v1/mcp/oauth-clients/:client_id`
-`GET /.well-known/oauth-protected-resource/mcp`
-`GET /.well-known/oauth-authorization-server/mcp`
-`POST /oauth/register`
-`GET /oauth/authorize`
-`POST /oauth/authorize`
-`POST /oauth/token`
-`POST /oauth/revoke`

Le développement local avec Phoenix s'exécute sur `http://localhost:4001`.

`POST /mcp` est le point de terminaison natif de MCP JSON-RPC. Les chemins `/mcp/tools` sont
Prend en charge les chemins REST pour les intégrations TextTree existantes et pour le débogage.
Actuellement, TextTree fonctionne avec le Streamable HTTP sans état : les messages JSON-RPC sont envoyés
avec `POST /mcp`. Sondes de flux SSE `GET /mcp` et demandes de fin de session
`DELETE /mcp` renvoie `405 Method Not Allowed` car aucune session MCP n'est allouée
du côté du serveur.

## Métadonnées de découverte

TextTree publie les métadonnées de découverte d'autorisation MCP sur les clients MCP HTTP :

```bash
boucler https://api.texttree.ai/.well-known/oauth-protected-resource/mcp
boucler https://api.texttree.ai/.well-known/oauth-authorization-server/mcp
```

Les requêtes MCP non authentifiées renvoient `401` avec un défi `WWW-Authenticate`
qui pointe vers l’URL des métadonnées de la ressource protégée. Métadonnées d'autorisation
annoncer la prise en charge du document de métadonnées d'ID client, l'enregistrement dynamique des clients,
octrois de code d'autorisation, PKCE S256 et échange de jetons client public pour les clients
MCP HTTP. TextTree continue également de prendre en charge l'amorçage des jetons au porteur premium
partie via `POST /mcp/accounts`. L’itinéraire rétrocompatible
`POST /api/v1/onboarding/api-key` émet désormais des jetons d'accès au porteur `txt_...`
qui utilisent MCP et API pour les développeurs.

Flux client MCP avec OAuth :

1. Préférez un document de métadonnées d'ID client : définissez `client_id` comme URL HTTPS qui
héberger les métadonnées client JSON. Utilisez `POST /oauth/register` uniquement comme
alternative d'enregistrement dynamique pour les clients qui ne peuvent pas héberger de métadonnées.
2. Envoyez l'utilisateur vers `GET /oauth/authorize` avec `response_type=code`,
`client_id`, `redirect_uri`, `resource=https://api.texttree.ai/mcp`,
`code_challenge` et `code_challenge_method=S256`.
3. TextTree affiche un écran de consentement dans le navigateur avec le client MCP, l'URI de redirection,
la ressource et la portée demandée. L'approbation envoie `POST /oauth/authorize` et
redirigez avec `code` ; le rejet redirige avec `error=access_denied`.
4. Échangez le code renvoyé dans `POST /oauth/token` avec le
`code_verifier` correspondant et la même valeur de `resource`. Les candidatures JSON sont acceptées et
`application/x-www-form-urlencoded`.
5. Utilisez le jeton du porteur TextTree renvoyé dans `POST /mcp`.
6. Révoquer un jeton au porteur en votre possession avec `POST /oauth/revoke` lorsque le client MCP
déconnectez-vous ou faites pivoter vos informations d’identification.

Exemple de document de métadonnées d'ID client :

```json
{
"id_client": "https://agent.example.com/.well-known/oauth-client.json",
"client_name": "Exemple d'agent",
"client_uri": "https://agent.example.com",
"redirect_uris": ["http://localhost:8787/callback"],
"grant_types": ["authorization_code"],
"response_types": ["code"],
"scope": "mcp:read mcp:execute onboarding:read",
"token_endpoint_auth_method": "aucun"
}
```

Lorsque TextTree voit un `client_id` au format URL lors de l'autorisation, il obtient
et valider ce document avant de montrer son consentement. L'URL du document doit utiliser
HTTPS sur le port par défaut, ne doit pas inclure d'informations d'identification ni de fragment, et doit
résoudre uniquement les adresses IP publiques. Hôtes localhost, privé, lien local, multidiffusion
et non résolus sont rejetés avant obtention. Le JSON obtenu doit contenir un
`client_id` qui correspond exactement à l'URL, un `client_name`, au moins un
portée prise en charge et le `redirect_uri` demandé. Si `grant_types` ou
`response_types` sont présents, ils doivent inclure `authorization_code` et `code`.
TextTree met en cache les métadonnées valides basées sur `Cache-Control: max-age` ou
`Expires`; `no-cache` et `no-store` forcent la revalidation au prochain
demande d'autorisation. Les documents sans en-têtes de cache utilisent une fenêtre de cache
La valeur par défaut est courte et TextTree limite la durée de vie du cache de métadonnées à un jour.

Les jetons au porteur TextTree peuvent être liés par audience à la ressource MCP. Les nouveaux jetons MCP
émis par l'opérateur doit utiliser l'URL canonique de la ressource MCP comme
public, par exemple `https://api.texttree.ai/mcp`. Les jetons sans audience continuent
étant accepté pour des raisons de compatibilité, mais un jeton lié à l'audience est rejeté lorsqu'il est utilisé
contre un autre appel TextTree.

La valeur OAuth `resource` est limitée à l'URL de la ressource MCP. Les portées
Les requêtes demandées non prises en charge échouent avec `invalid_scope` au lieu de se développer
ou réduire silencieusement.

Les clients OAuth MCP autorisés peuvent être répertoriés et révoqués via API :

```bash
boucle https://api.texttree.ai/oauth/revoke \
-H "Type de contenu : application/x-www-form-urlencoded" \
-d "jeton=$TEXTREE_ACCESS_TOKEN&token_type_hint=access_token"

boucle https://api.texttree.ai/api/v1/mcp/oauth-clients \
-H "Autorisation : Porteur $TEXTREE_ACCESS_TOKEN"

curl -X SUPPRIMER https://api.texttree.ai/api/v1/mcp/oauth-clients/mcp_client_... \
-H "Autorisation : Porteur $TEXTREE_ACCESS_TOKEN"
```

`POST /oauth/revoke` suit la convention de révocation de OAuth et renvoie `200`
pour les jetons inconnus, afin que les appelants ne divulguent pas l'existence des jetons.
La liste nécessite `mcp:read`. La révocation nécessite `mcp:execute` et révoque
les jetons au porteur TextTree actifs émis via ce client OAuth MCP pour le
utilisateur actuel.

`POST /oauth/register` et `POST /oauth/token` ont des limites de débit par adresse IP client.
Les requêtes à débit limité renvoient `429` avec un en-tête `Retry-After` et
`oauth_client_registration_rate_limited` et `oauth_token_exchange_rate_limited`.
Les compartiments sont indépendants, de sorte que les pics d'inscription ne drainent pas les échanges de jetons
code d'autorisation.

## Authentification et portées

Les requêtes MCP authentifiées utilisent des jetons de support émis par TextTree. Les humains, les utilisateurs
le portefeuille et les agents IA présentent le même en-tête `Authorization: Bearer <token>`
après authentification via TextTree.

Les agents IA peuvent démarrer leur propre identité à partir de TextTree à l'aide de `POST /mcp/accounts`
avec un nom d'utilisateur et un mot de passe. Cette route ne nécessite pas d'authentification, elle renvoie des codes
sauvegarde plus un jeton au porteur de TextTree, et est limité à la création réussie d'un compte
par adresse IP toutes les cinq minutes.

Les portées actuelles au niveau de l'itinéraire sont :

- `POST /mcp` accepte `initialize` et `ping` avec n'importe quel jeton authentifié
- `POST /mcp` `tools/list`, `resources/list`, `resources/templates/list`, `prompts/list` et `completion/complete` nécessitent `mcp:read`
- `POST /mcp` `resources/read` nécessite une portée spécifique à la ressource
- `POST /mcp` `tools/call` nécessite `mcp:execute`
- `GET /mcp/tools` nécessite `mcp:read`
- `POST /mcp/tools/:name` nécessite `mcp:execute`
- `GET /api/v1/mcp/oauth-clients` nécessite `mcp:read`
- `DELETE /api/v1/mcp/oauth-clients/:client_id` nécessite `mcp:execute`

Les entrées de l'outil peuvent également déclarer une portée requise plus spécifique dans le journal du serveur. Si ça
se produit, TextTree enregistre un audit d'exécution bloqué et renvoie `403 insufficient_scope`.

## MCP RPC natif JSON

`POST /mcp`

TextTree prend en charge MCP-RPC de style JSON sur HTTP pour les clients attendant les méthodes
Norme MCP. Le point de terminaison nécessite un jeton de support de TextTree et renvoie le
en-tête de réponse `mcp-protocol-version`.
Les wrappers de requête JSON-RPC doivent inclure `jsonrpc: "2.0"`. Les ID de demande doivent être
des chaînes ou des entiers ; Les identifiants explicites `null` sont rejetés et les formulaires d'identification non valides ne sont pas
ils se répètent dans les réponses d'erreur. Les noms de méthodes doivent être des chaînes. Emballages d'application
sont stricts : uniquement `jsonrpc`, `id`, `method`, `params` et le champ
niveau supérieur réservé par MCP `_meta`. Chaque champ `_meta` doit être un objet JSON.
Lorsque les paramètres de la requête incluent `_meta.progressToken`, le jeton doit être une chaîne ou
un entier. TextTree traite actuellement les jetons de progression comme des métadonnées consultatives et non
Émet des notifications de progression.

Versions de protocole prises en charge :

- `2025-11-25`
- `2025-06-18`
- `2025-03-26`

Pendant `initialize`, TextTree négocie le `params.protocolVersion` demandé
quand il est pris en charge. Si une demande d'initialisation demande une version de chaîne non prise en charge,
TextTree répond avec sa dernière version prise en charge au lieu d'échouer
la poignée de main. Pour les demandes ultérieures, les clients doivent envoyer le
en-tête `MCP-Protocol-Version` avec la version négociée. S'il n'y a pas d'en-tête
présent, TextTree revient à `2025-03-26` pour des raisons de compatibilité. En-têtes de version
Les codes de protocole non pris en charge renvoient `400 Bad Request`, conformément aux exigences de transport
MCP HTTP diffusable.
S'il est fourni, `initialize.params.protocolVersion` doit être une chaîne,
`capabilities` doit être un objet et `clientInfo` doit être un objet avec un
`name` de type chaîne et un `version` facultatif de type chaîne. Les paramètres d'initialisation inconnus sont
sont rejetés, à l'exception du champ `_meta` réservé par MCP.
`ping` accepte un objet params vide ou `_meta` ; les autres paramètres de ping sont rejetés.

`POST /mcp` nécessite un en-tête `Accept` qui inclut à la fois `application/json`
comme `text/event-stream`, plus `Content-Type: application/json`. sondes de débit
`GET /mcp` nécessite `text/event-stream`. Requêtes qui ignorent les types de réponse
retour annoncé `406 Not Acceptable` ; Requêtes POST avec un type de contenu
autre que JSON, renvoie `415 Unsupported Media Type`.

Les demandes de transport MCP provenant du navigateur doivent également réussir la validation Origin.
Les requêtes sans en-tête `Origin` sont acceptées pour les clients MCP côté serveur et CLI.
Lorsqu'un entête `Origin` est présent, il doit correspondre à la source de la requête,
la source configurée de l'application ou du site public TextTree, ou une source de développement
bouclage local. Les sources de navigateur non fiables renvoient `403 forbidden_origin`.

### Initialiser

```bash
boucle https://api.texttree.ai/mcp \
-H "Autorisation : Porteur $TEXTREE_ACCESS_TOKEN" \
-H "Accepter : application/json, text/event-stream" \
-H "Type de contenu : application/json" \
-d '{
"jsonrpc": "2.0",
"id": "init-1",
"method": "initialiser",
"paramètres": {
"protocolVersion": "2025-11-25",
"capacités": {},
"Infoclient": {
"name": "agent-client",
"version": "0.1.0"
      }
    }
  }'
```

Le succès renvoie les capacités et l'identité du serveur :

```json
{
"jsonrpc": "2.0",
"id": "init-1",
"résultat": {
"protocolVersion": "2025-11-25",
"capacités": {
"invites": {
"listChanged": faux
      },
"achèvements": {},
"ressources": {
"listChanged": faux
      },
"outils": {
"listChanged": faux
      }
    },
"Infosserveur": {
"name": "arbre de texte",
"version": "0.1.0"
    },
"instructions": "TextTree expose les workflows audités d'intégration et de messagerie de SMS..."
  }
}
```

Les clients peuvent placer le `instructions` renvoyé dans le contexte du modèle. Le
Les instructions résument les règles de flux de travail spécifiques au TextTree : Préférer Dédié
Numéro pour une identité d'expéditeur stable, lisez les ressources avant d'exécuter les outils, utilisez
`messages.send` uniquement avec un SMS approuvé par le destinataire et un `idempotency_key`
stable et s'appuie sur des portes de suppression, de dépenses et de préparation de l'expéditeur
et livreur TextTree pour les expéditions de production.

### Liste des outils MCP

```bash
boucle https://api.texttree.ai/mcp \
-H "Autorisation : Porteur $TEXTREE_ACCESS_TOKEN" \
-H "Accepter : application/json, text/event-stream" \
-H "Type de contenu : application/json" \
-d '{
"jsonrpc": "2.0",
"id": "outils-1",
"method": "outils/liste",
"paramètres": {}
  }'
```

`tools/list` nécessite `mcp:read`. Chaque outil comprend un titre, un schéma JSON `inputSchema`
2020-12, un `outputSchema` du schéma JSON 2020-12, annotations de sécurité de MCP
et les métadonnées TextTree pour la portée et le délai d'expiration requis.
`tools/list` prend en charge la pagination du curseur MCP. Traite `nextCursor` comme opaque et
renvoyez-le sous le nom `params.cursor` uniquement lors de la prochaine requête pour `tools/list`. Les demandes
les listings acceptent uniquement `cursor` et le champ `_meta` réservé par MCP.

### Liste des ressources MCP

```bash
boucle https://api.texttree.ai/mcp \
-H "Autorisation : Porteur $TEXTREE_ACCESS_TOKEN" \
-H "Accepter : application/json, text/event-stream" \
-H "Type de contenu : application/json" \
-d '{
"jsonrpc": "2.0",
"id": "ressources-1",
"method": "ressources/liste",
"paramètres": {}
  }'
```

`resources/list` nécessite `mcp:read`. Les ressources exposent un contexte en lecture seule avec
métadonnées de portée afin que les agents puissent inspecter l’état sans exécuter d’outil.
`resources/list` prend en charge la pagination du curseur MCP. Traiter `nextCursor` comme opaque
et renvoyez-le sous le nom `params.cursor` uniquement dans la prochaine requête pour `resources/list`.
Les demandes de listage acceptent uniquement `cursor` et le champ `_meta` réservé par MCP.

Ressources actuelles :

- `texttree://mcp/tools` nécessite `mcp:read`
- `texttree://onboarding/status` nécessite `onboarding:read`
- `texttree://billing/status` nécessite `onboarding:read`
- `texttree://messages/recent` nécessite `messages:write`

### Répertorier les modèles de ressources MCP

```bash
boucle https://api.texttree.ai/mcp \
-H "Autorisation : Porteur $TEXTREE_ACCESS_TOKEN" \
-H "Accepter : application/json, text/event-stream" \
-H "Type de contenu : application/json" \
-d '{
"jsonrpc": "2.0",
"id": "modèles-de-ressources-1",
"method": "ressources/modèles/liste",
"paramètres": {}
  }'
```

`resources/templates/list` nécessite `mcp:read` et renvoie des modèles de ressources
sécurisé par ID pour l'interrogation des agents :

- `texttree://invoices/{id}` nécessite `onboarding:read`
- `texttree://messages/{id}` nécessite `messages:write`
- `texttree://numbers/{id}` nécessite `numbers:read`
- `texttree://onboarding/checklist` nécessite `onboarding:read`
- `texttree://billing/readiness` nécessite `onboarding:read`
- `texttree://elicitations/{correlation_id}` nécessite `onboarding:read`

Prend en charge le même contrat de pagination de curseur que les autres méthodes de listage, et
accepte uniquement `cursor` plus le champ `_meta` réservé par MCP.

### Lire une ressource MCP

```bash
boucle https://api.texttree.ai/mcp \
-H "Autorisation : Porteur $TEXTREE_ACCESS_TOKEN" \
-H "Accepter : application/json, text/event-stream" \
-H "Type de contenu : application/json" \
-d '{
"jsonrpc": "2.0",
"id": "ressource-read-1",
"method": "ressources/lecture",
"paramètres": {
"uri": "texttree://onboarding/status"
    }
  }'
```

`resources/read` renvoie le contenu JSON dans le tableau `contents` de MCP. Les lectures
Les gestionnaires de ressources appliquent la portée TextTree spécifique à la ressource avant de renvoyer les données.
`texttree://messages/recent` et `texttree://messages/{id}` ignorent les numéros de téléphone
et les corps des messages ; utilisez-les pour le contexte de l'état de livraison, pas pour le contenu privé
du destinataire. `texttree://numbers/{id}` masque le numéro de téléphone complet et renvoie
l'état, l'utilisation, les capacités et l'état de conformité. Toutes les lectures par ID sont limitées au
utilisateur ou espace de travail actuel de TextTree. `texttree://elicitations/{correlation_id}`
renvoie l'état pouvant être repris d'un transfert en mode URL de financement, de consentement ou de configuration
de numéro.

### Liste des invites MCP

```bash
boucle https://api.texttree.ai/mcp \
-H "Autorisation : Porteur $TEXTREE_ACCESS_TOKEN" \
-H "Accepter : application/json, text/event-stream" \
-H "Type de contenu : application/json" \
-d '{
"jsonrpc": "2.0",
"id": "invites-1",
"method": "invites/liste",
"paramètres": {}
  }'
```

`prompts/list` nécessite `mcp:read`. Package d’invites pour les flux de travail TextTree courants
dans des instructions réutilisables pour les agents.
`prompts/list` prend en charge la pagination du curseur MCP. Traite `nextCursor` comme opaque et
renvoyez-le sous le nom `params.cursor` uniquement lors de la prochaine requête pour `prompts/list`. Les demandes
les listings acceptent uniquement `cursor` et le champ `_meta` réservé par MCP.

Invites actuelles :

- `texttree.onboard_agent` accepte en option `path` (`dedicated_number` ou
`fast_send`), `region`, `brand_name`, `website`, `funding_amount_cents`,
`payment_method`, `recipient_phone_number`, `secret_storage` et
`execution_policy`
- `texttree.first_send` accepte en option `sender_path` (`dedicated_number` ou
`fast_send`) et une chaîne facultative `recipient_context`

Les arguments rapides sont stricts. Noms d'arguments inconnus, types et valeurs incorrects
L'énumération du chemin de l'expéditeur non valide renvoie `-32602 Invalid params`.

### Obtenez une invite MCP

```bash
boucle https://api.texttree.ai/mcp \
-H "Autorisation : Porteur $TEXTREE_ACCESS_TOKEN" \
-H "Accepter : application/json, text/event-stream" \
-H "Type de contenu : application/json" \
-d '{
"jsonrpc": "2.0",
"id": "invite-1",
"method": "invites/get",
"paramètres": {
"name": "texttree.onboard_agent",
"arguments": {
"chemin": "numéro_dédié",
"region": "États-Unis"
      }
    }
  }'
```

Les réponses rapides renvoient `messages` de MCP qu'un client peut placer dans le contexte
du modèle avant d’appeler des ressources ou des outils.

### Compléter les arguments d'invite MCP

```bash
boucle https://api.texttree.ai/mcp \
-H "Autorisation : Porteur $TEXTREE_ACCESS_TOKEN" \
-H "Accepter : application/json, text/event-stream" \
-H "Type de contenu : application/json" \
-d '{
"jsonrpc": "2.0",
"id": "complète-1",
"method": "achèvement/complet",
"paramètres": {
"réf": {
"type": "réf/invite",
"name": "texttree.onboard_agent"
      },
"argument": {
"name": "chemin",
"valeur": "d"
      }
    }
  }'
```

`completion/complete` nécessite `mcp:read` et renvoie des astuces non sensibles
pour les arguments d’invite TextTree. Les achèvements actuels couvrent `path`,
`sender_path` et `region`. Les arguments de forme libre renvoient une liste de complétion
vide. TextTree n'expose pas les modèles de ressources, donc les demandes d'achèvement
des modèles de ressources renvoient `-32602 Invalid params`.

### Appeler un outil MCP

```bash
boucle https://api.texttree.ai/mcp \
-H "Autorisation : Porteur $TEXTREE_ACCESS_TOKEN" \
-H "Accepter : application/json, text/event-stream" \
-H "Type de contenu : application/json" \
-d '{
"jsonrpc": "2.0",
"id": "appel-1",
"method": "outils/appel",
"paramètres": {
"name": "onboarding.status",
"arguments": {}
    }
  }'
```

`tools/call` nécessite `mcp:execute` plus la portée de l'outil spécifique déclarée dans
le dossier. Les résultats incluent MCP `content`, `structuredContent`, `isError`,
`_meta` de MCP et le wrapper d'audit d'exécution de TextTree. La charge
`structuredContent` correspond au `outputSchema` annoncé pour chaque outil.
Le `_meta` du résultat de l'appel d'outil contient des champs de corrélation sécurisés :
`texttree/execution_id`, `texttree/tool`, `texttree/outcome` et
`texttree/is_error`. Les mêmes métadonnées sont incluses sous
`structuredContent._meta` afin que le `outputSchema` annoncé corresponde à la charge
résultat lisible par machine. N'inclut pas les numéros de téléphone ni les organismes de
messages.

TextTree valide les arguments connus de l'outil par rapport au `inputSchema` annoncé
de chaque outil avant exécution. Champs obligatoires manquants, champs inconnus, types
Les valeurs d'énumération incorrectes et non valides et les violations minimales renvoient `-32602 Invalide
params` sans exécuter l’outil.
Les paramètres des méthodes JSON-RPC sont également stricts : `prompts/get`, `resources/read` et
`tools/call` rejette les paramètres de niveau supérieur inconnus et accepte le champ `_meta`
réservé par MCP. Le `_meta` de l'appel à l'outil est transmis au contexte de l'exécuteur sous la forme
métadonnées MCP du canal latéral et n'est pas fusionné avec le `arguments` de l'outil.
Si `_meta.progressToken` est présent, il doit s'agir d'une chaîne ou d'un entier.
Les outils de message `arguments.metadata` sont des métadonnées distinctes appartenant à l'appelant et peuvent
contiennent des champs d'objet JSON arbitraires pour la corrélation.

`messages.send` est un véritable outil MCP. Il est mis en file d'attente par la même route de messagerie
de TextTree que `POST /api/v1/messages`, y compris la suppression, les dépenses et
livreur. Ses notes MCP la qualifient de destructrice et
monde ouvert car il peut mettre en file d'attente un SMS sortant et consommer le solde du compte.

Les erreurs JSON-RPC utilisent des wrappers de réponse standard de style MCP et préservent
les détails de sécurité de TextTree dans `error.data`, y compris `required_scope`,
`quota_exceeded`, `tool_not_allowed`, le délai d'expiration d'exécution et les données d'audit lorsque
sont disponibles.

### Lots et notifications

Les packages JSON-RPC sont acceptés uniquement lorsque la version effective du protocole est
version de compatibilité `2025-03-26`. Les révisions ultérieures de MCP ont supprimé les messages par lots
du schéma de protocole, donc les clients négociant `2025-06-18` ou
`2025-11-25` doit envoyer un message JSON-RPC pour chaque `POST /mcp` ; arrangements de lots dans
ces versions renvoient `-32600 Invalid Request` avec `error.data.error` défini sur
`batch_not_supported`.

Pour les packages de compatibilité `2025-03-26`, TextTree renvoie un objet de réponse pour
demande et ignore les réponses aux notifications et aux messages de réponse JSON-RPC.
Les lots de notification uniquement et de réponse uniquement renvoient `202` avec un corps vide.
Actuellement, TextTree n'initie pas de requêtes serveur-client.
Les réponses des clients sont acceptées comme entrées de transport nulles lorsqu'elles incluent un
`id` chaîne ou entier valide. Les messages de réponse aux résultats doivent inclure un `result`
de type objet ; les messages de réponse d'erreur doivent inclure un `error` de type objet avec un `code`
entier et un `message` de type chaîne. Envoie `initialize` sous forme de requête distincte ; oui
apparaît dans un lot, TextTree renvoie `-32600 Invalid Request` pour cet élément
du lot. Les packs de compatibilité sont limités à 100 articles ; les lots plus grands rapportent un
seule réponse `-32600 Invalid Request` avec `error.data.error` défini sur
`batch_too_large`.
Les méthodes de l'espace de noms `notifications/` sont traitées comme des notifications de type
tirez et oubliez, et ne recevez jamais de réponses JSON-RPC. Actuellement, TextTree agit sur
`notifications/initialized` et accepter les avis d'annulation à titre consultatif ;
Les noms de notification inconnus sont ignorés. Méthodes de requête ordinaires comme
`ping`, `tools/list` et `tools/call` doivent inclure un `id`.

```bash
boucle https://api.texttree.ai/mcp \
-H "Autorisation : Porteur $TEXTREE_ACCESS_TOKEN" \
-H "Accepter : application/json, text/event-stream" \
-H "Type de contenu : application/json" \
-d '[
    {
"jsonrpc": "2.0",
"identifiant": "ping-1",
"méthode": "ping",
"paramètres": {}
    },
    {
"jsonrpc": "2.0",
"method": "notifications/initialisées",
"paramètres": {}
    },
    {
"jsonrpc": "2.0",
"id": "outils-1",
"method": "outils/liste",
"paramètres": {}
    }
  ]'
```

### Test de fumée de compatibilité

Pour un serveur Phoenix en cours d'exécution, TextTree inclut une tâche de test de compatibilité qui
parcourt le point de terminaison natif MCP via initialize, la notification initialisée,
des outils, des ressources, des invites et un appel à l'outil d'état d'intégration.

```bash
applications cd/web
TEXTREE_ACCESS_TOKEN=txt_... mix textree.mcp.smoke --url http://localhost:4001/mcp
mélanger textree.mcp.smoke --url http://localhost:4001/mcp --bootstrap-local-token
```

Le jeton doit inclure `mcp:read`, `mcp:execute` et `onboarding:read`.
Passez `--skip-execute` pour ignorer l'appel de l'outil d'état d'intégration lors de la validation
un jeton en lecture seule. `--bootstrap-local-token` crée un jeton d'une heure dans le
base de données locale actuelle et est rejeté pour les URL MCP autres que localhost.

Pour les jetons au porteur émis par l'opérateur, liez le jeton à la ressource MCP :

```bash
mélanger textree.auth.issue_token agent@example.com \
--scopes mcp:lire,mcp:exécuter,intégration:lire,messages:écrire \
--public https://api.texttree.ai/mcp
```

## Outils de liste

`GET /mcp/tools`

```bash
boucle https://api.texttree.ai/mcp/tools \
-H "Autorisation : Porteur $TEXTREE_ACCESS_TOKEN"
```

Le succès renvoie une liste d'outils sauvegardée par le registre :

```json
{
"outils": [
    {
"name": "messages.envoyer",
"description": "Déclencher l'envoi d'un message via la surface MCP.",
"required_scope": "messages:écriture",
"timeout_ms" : 1000
    },
    {
"name": "onboarding.status",
"description": "Inspecter le jeton, le solde, la facture et l'état d'intégration du SMS.",
"required_scope": "intégration : lecture",
"timeout_ms" : 1000
    },
    {
"name": "onboarding.create_invoice",
"description": "Créer ou réutiliser une facture de financement de lancement.",
"required_scope": "intégration :écriture",
"timeout_ms" : 1000
    },
    {
"name": "onboarding.invoice_status",
"description": "Vérifier le statut de la facture de financement pour l'intégration programmatique.",
"required_scope": "intégration : lecture",
"timeout_ms" : 1000
    },
    {
"name": "onboarding.test_sms",
"description": "Envoyer le test d'intégration Fast Send fixe SMS.",
"required_scope": "intégration :écriture",
"timeout_ms" : 1000
    },
    {
"name": "onboarding.request_dedicated_number",
"description": "Soumettez les détails de l'entreprise pour le chemin du numéro dédié recommandé.",
"required_scope": "intégration :écriture",
"timeout_ms" : 1000
    }
  ]
}
```

L'enregistrement alpha actuel est configuré côté serveur. Il n’y a pas de surface d’administration publique à muter
le journal au moment de l'exécution.

## Créer un compte sans tête

`POST /mcp/accounts`

Utilisez cette route lorsqu'un client AI a besoin d'un compte et d'un porteur de jeton sans
e-mail, Google OAuth ou authentification par portefeuille.

```bash
boucle https://api.texttree.ai/mcp/accounts \
-H "Type de contenu : application/json" \
-d '{
"compte": {
"username": "agent-demo",
"mot de passe": "agrafe de batterie de cheval correcte"
    }
  }'
```

Le succès renvoie le nom d'utilisateur public, les codes de sauvegarde à usage unique et un jeton de porteur :

```json
{
"compte": {
"identifiant": "9d7d9df7-58a0-4716-b82e-7ad5e73f7b36",
"nom d'utilisateur": "agent-démo"
  },
"backup_codes": ["AAAA-BBBB-CCCC-DDDD"],
"jeton": {
"type": "Porteur",
"access_token": "txt_...",
"portées": [
"messages:écrire",
"mcp:lire",
"mcp:exécuter",
"campagnes :lire",
"campagnes :écrire",
"chiffres :lire",
"nombres :écrire",
"intégration :lire",
"intégration : écrire"
    ],
"expires_at": "2026-06-03T15:30:00Z"
  }
}
```

Enregistrez immédiatement le jeton et les codes de sauvegarde. TextTree ne renvoie pas le
e-mail synthétique interne, hachage de jeton, adresse IP brute ou hachage IP. Échecs de validation
renvoie `422 validation_failed` ; la création réussie et répétée de comptes à partir du
la même IP dans les cinq minutes renvoie `429 account_creation_rate_limited`.

Les jetons de compte sans interface incluent une valeur `expires_at`. Intégrations d'agents
Les jetons durables doivent utiliser un jeton émis par l'opérateur avec une durée de vie utile et une audience
intentionnel, ou inclure un plan de réémission et de rotation du jeton. Non
stocke les jetons de support bruts et les codes de sauvegarde dans les journaux, l'historique du shell et les fichiers
engagé dans le référentiel.

## Invite d'intégration sécurisée MCP

Utilisez une invite avec des objectifs explicites du monde réel et des limites d'approbation avant un
configuration de démarrage de l'agent :

```txt
Configurer TextTree.ai SMS pour mon agent IA à l'aide de https://texttree.ai/docs/mcp/.
Générer automatiquement les informations d'identification du compte ; enregistrer le numéro dédié sous la marque
"AlphaGrowth" / https://alphagrowth.io/ (États-Unis). Stockez le jeton et les codes de sauvegarde
dans un .env gitignoré. Créez une facture de financement USDC de 100 $ et donnez-moi le
détails du dépôt à payer ; ne tentez pas de payer vous-même. Une fois financé, envoyez un
testez SMS sur +1XXXXXXXXXX et montrez-moi comment interroger les réponses entrantes ; je vais
envoyez moi-même le numéro par SMS pour tester l'arrivée. Enregistrez ensuite le numéro attribué, base API
L'URL, l'emplacement du jeton et les étapes de connexion MCP à un fichier README et écrivent en direct et
scripts de test bash/curl simulés pour l'envoi et la réception. Pause pour mon OK avant
tout ce qui dépense de l'argent, approvisionne ou modifie un numéro, ou envoie un SMS.
```

S'il manque l'un des éléments suivants : numéro de téléphone, marque, site internet, mode de financement,
destination de stockage secrète ou limite d’approbation, collectez-la avant d’exécuter les outils.
Les agents ne doivent pas inventer des numéros de destinataires, effectuer des paiements ou simuler SMS.
les appels entrants qui nécessitent un téléphone appartenant à un humain.

## Intégration du runbook MCP

Étapes exécutables par l'agent :

1. Créez ou choisissez un porteur de jeton et stockez-le dans la destination des secrets demandée.
2. Lisez `texttree://onboarding/status` et `texttree://billing/status`.
3. Après approbation explicite, appelez uniquement `onboarding.request_dedicated_number`
lorsque le nom de la marque, le site Web HTTPS et la région sont explicites.
4. Après approbation explicite, appelez `onboarding.create_invoice` avec un montant
explicite et une méthode prise en charge, puis donne à l'humain les détails du paiement
est revenu.
5. Interrogez `onboarding.invoice_status` ou `texttree://invoices/{id}` jusqu'à ce que l'état
des changements de paiement.
6. Après approbation, appelez `onboarding.test_sms` ou `messages.send` avec le
le numéro de téléphone explicite du destinataire et un `idempotency_key` stable.
7. Sondez `/api/v1/messages/$MESSAGE_ID` ou `texttree://messages/{id}` pour le savoir
l'état de livraison.

Etapes de paiement par l'humain :

1. Vérifiez le montant de la facture, la chaîne, le jeton, le portefeuille et l'expiration.
2. Payez la facture en dehors de l'agent.
3. Dites à l'agent de reprendre le sondage une fois le paiement envoyé.

Étapes de test des entrées humaines :

1. Attendez que le numéro attribué soit connecté.
2. Envoyez un message texte au numéro attribué à partir d'un vrai téléphone.
3. Invite l'agent à recevoir des commandes d'interrogation ou des étapes d'inspection du webhook.

Étapes nécessitant une approbation explicite :

- Créer un virement de financement ou une facture destinée à un paiement effectif.
- Demander, mettre à disposition ou modifier un numéro dédié.
- Envoyez n'importe quel SMS à un vrai numéro de téléphone.
- Stockez ou faites pivoter les jetons du porteur et les codes de sauvegarde.

## Exécuter un outil

`POST /mcp/tools/:name`

### Corps de la requête

```json
{
"paramètres": {}
}
```

### boucle

```bash
boucle https://api.texttree.ai/mcp/tools/onboarding.status \
-H "Autorisation : Porteur $TEXTREE_ACCESS_TOKEN" \
-H "Type de contenu : application/json" \
-d '{"params": {}}'
```

### JavaScript

```js
réponse const = wait fetch("https://api.texttree.ai/mcp/tools/onboarding.status", {
méthode : "POST",
en-têtes : {
Autorisation : `Bearer ${process.env.TEXTREE_ACCESS_TOKEN}`,
"Content-Type": "application/json",
  },
corps : JSON.stringify({ params : {} }),
});

const { exécution } = wait réponse.json();
```

### Réponse réussie

```json
{
"exécution": {
"identifiant": "513f6a41-2c33-4c15-b4e2-10da14ab806f",
"tool": "onboarding.status",
"résultat": "réussi",
"params_summary": {},
"result_summary": {
"complet": faux,
"product_mode": "instant_send"
    },
"message_erreur": nul,
"durée_ms": 3,
"inséré_at": "2026-04-26T21:02:15Z"
  }
}
```

## Réponses d'erreur

- `403` avec `{"error":"tool_not_allowed"}` lorsque l'outil est en dehors de la liste verte configurée
- `403` avec `{"error":"insufficient_scope","required_scope":"..."}` lorsque le jeton n'a pas le
portée au niveau du chemin ou au niveau de l'outil
- `429` avec `{"error":"quota_exceeded"}` lorsque la fenêtre de quota par identité est épuisée
- `504` avec `{"error":"execution_timed_out"}` lorsque l'exécution dépasse le timeout configuré
- `422` avec `{"error":"execution_failed"}` lorsque l'exécuteur renvoie une erreur

Tous ces chemins d'exécution renvoient un wrapper `execution` lorsque TextTree a pu créer un
journal d'audit.

Les réponses MCP `403 insufficient_scope` incluent également un défi `WWW-Authenticate`
avec `error="insufficient_scope"`, le `scope` requis et le
URL des métadonnées de la ressource protégée. Les clients MCP peuvent utiliser cet en-tête pour déclencher un
Flux d'autorisation échelonné et demande de portée manquante sans deviner.

##  Contrôles d'exécution

Le runtime alpha actuel de MCP est intentionnellement strict :

- l'exécution est conditionnée par la portée des tokens au porteur TextTree
- les outils doivent exister dans le registre du serveur
- les outils doivent également être présents dans la limite de la liste verte
- les exécutions sont conservées avec l'acteur, l'identité du jeton, l'outil, le résumé des paramètres, le résultat et l'horodatage
- Les frais d'identité sont appliqués sur une fenêtre glissante
- Les délais d'attente par outil ou globaux arrêtent les travaux de longue durée
- L'enregistrement du client OAuth et l'échange de jetons ont des limites de débit distinctes par IP

Valeurs par défaut de la limite de débit OAuth et variables d'environnement de production :

- enregistrement client : 20 requêtes par IP, recharge toutes les 60 secondes avec
`TEXTREE_OAUTH_CLIENT_REGISTRATION_RATE_LIMIT_CAPACITY` et
`TEXTREE_OAUTH_CLIENT_REGISTRATION_RATE_LIMIT_REFILL_MS`
- échange de tokens : 60 requêtes par IP, recharge toutes les 60 secondes avec
`TEXTREE_OAUTH_TOKEN_EXCHANGE_RATE_LIMIT_CAPACITY` et
`TEXTREE_OAUTH_TOKEN_EXCHANGE_RATE_LIMIT_REFILL_MS`

## Modèle d'intégration programmatique

Utilisez les outils d'intégration API et MCP pour terminer la configuration sans deviner lequel
est la prochaine étape. Le numéro dédié est l'itinéraire recommandé lorsqu'un agent a besoin d'un
expéditeur persistant auquel les gens peuvent enregistrer et auquel répondre. Fast Send est disponible
lorsque l'objectif est le premier test d'expédition sortant le plus rapide via les expéditeurs
instantanés regroupés.

### 1. Créez ou choisissez un jeton

Créez un compte sans tête en utilisant `POST /mcp/accounts` ou créez un porteur de jeton
depuis TextTree dans l'application authentifiée avec les plages nécessaires à votre itinéraire :

- `onboarding:read` pour inspecter l'état de l'intégration et les factures
- `onboarding:write` pour créer des factures, tester des envois et des demandes de numéros dédiés
- `messages:write` pour envoyer la première production SMS via `/api/v1/messages`
- `mcp:read` et `mcp:execute` pour lister et exécuter les outils MCP

N’utilisez pas de clé API héritée `txk_...` pour ce flux. `POST
/api/v1/onboarding/api-key` devuelve un token bearer `txt_...` pour les appelants qui
Ils disposent déjà d’un jeton avec une portée d’intégration.

Les jetons au porteur émis par le transporteur doivent être créés avec les portées exactes dont vous avez besoin
le client. Pour l’intégration de MCP plus le premier envoi, utilisez :

```bash
cd apps/web && mix textree.auth.issue_token agent@example.com \
--scopes intégration : lecture, intégration : écriture, mcp : lecture, mcp : exécution, messages : écriture \
--public https://api.texttree.ai/mcp
```

Enregistrez immédiatement les jetons retournés. Les jetons bruts ne sont affichés qu'une seule fois.

### 2. Vérifiez le statut d'intégration

Utilisez l'outil API ou MCP pour inspecter la progression du jeton, du solde, de la facture, du numéro et
le premier SMS.

```bash
boucle https://api.texttree.ai/api/v1/onboarding \
-H "Autorisation : Porteur $TEXTREE_ACCESS_TOKEN"
```

```bash
boucle https://api.texttree.ai/mcp/tools/onboarding.status \
-H "Autorisation : Porteur $TEXTREE_ACCESS_TOKEN" \
-H "Type de contenu : application/json" \
-d '{"params": {}}'
```

### 3. Choisissez un itinéraire numérique

Recommandé : numéro dédié. Utilisez-le lorsque l'agent a besoin d'un expéditeur stable,
des réponses entrantes, une reconnaissance par les clients ou un numéro que les opérateurs peuvent gérer. Le
L'outil natif MCP enregistre les détails de l'entreprise et renvoie les métadonnées d'élicitation en mode URL
qui pointent vers le flux de configuration hébergé TextTree.

```bash
boucle https://api.texttree.ai/mcp \
-H "Autorisation : Porteur $TEXTREE_ACCESS_TOKEN" \
-H "Accepter : application/json, text/event-stream" \
-H "Type de contenu : application/json" \
-d '{
"jsonrpc": "2.0",
"id": "numéro-dédié-1",
"method": "outils/appel",
"paramètres": {
"name": "onboarding.request_dedicated_number",
"arguments": {
"brand_name": "Assistance Acme",
"site Web": "https://acme.example",
"region": "États-Unis"
      }
    }
  }'
```

Fast Send. Utilisez-le pour le premier test d'expédition sortant le plus rapide lorsqu'un
numéro dédié. L'outil natif MCP envoie un texte de test d'intégration fixe
via le même itinéraire de test Fast Send que API.

```bash
boucle https://api.texttree.ai/mcp \
-H "Autorisation : Porteur $TEXTREE_ACCESS_TOKEN" \
-H "Accepter : application/json, text/event-stream" \
-H "Type de contenu : application/json" \
-d '{
"jsonrpc": "2.0",
"id": "test-sms-1",
"method": "outils/appel",
"paramètres": {
"name": "onboarding.test_sms",
"arguments": {
"numéro_téléphone": "+15551234567"
      }
    }
  }'
```

`test-sms` utilise un texte d'intégration fixe, peut s'exécuter avant le financement lors du compte
dispose d’une allocation disponible de Fast Send Sandbox et son débit est plafonné. une demande
répété peut renvoyer `429 test_sms_rate_limited` avec `next_allowed_at` ; après ça
utilisez le bac à sable SMS inclus, continuez à ajouter de l'équilibre.

### 4. Financer l'espace de travail

Créez ou réutilisez une facture de financement de lancement avec un montant qui satisfait aux
intégration actuelle minimale. Préférez l'outil de facturation MCP lors de l'intégration
d'agents. Le résultat inclut des métadonnées d'élicitation en mode URL avec une URL d'action
hébergé par TextTree pour finaliser le paiement.

```bash
boucle https://api.texttree.ai/mcp/tools/onboarding.create_invoice \
-H "Autorisation : Porteur $TEXTREE_ACCESS_TOKEN" \
-H "Type de contenu : application/json" \
-d '{
"paramètres": {
"montant_cents": 10000,
"payment_method": "direct_usdc"
    }
  }'
```

Interrogez la facture jusqu'à ce qu'elle devienne `paid`, `underpaid`, `expired` ou
`review_required`.

```bash
boucle https://api.texttree.ai/api/v1/onboarding/funding-invoices/$INVOICE_ID \
-H "Autorisation : Porteur $TEXTREE_ACCESS_TOKEN"
```

```bash
boucle https://api.texttree.ai/mcp/tools/onboarding.invoice_status \
-H "Autorisation : Porteur $TEXTREE_ACCESS_TOKEN" \
-H "Type de contenu : application/json" \
-d '{
"paramètres": {
"identifiant": "'"$INVOICE_ID"'"
    }
  }'
```

Pour `onboarding.invoice_status`, indiquez exactement l'un des éléments suivants : `id` ou `invoice_id`.
Le modèle de ressource par ID peut également être utilisé pour l'interrogation :

```bash
boucle https://api.texttree.ai/mcp \
-H "Autorisation : Porteur $TEXTREE_ACCESS_TOKEN" \
-H "Accepter : application/json, text/event-stream" \
-H "Type de contenu : application/json" \
-d '{
"jsonrpc": "2.0",
"id": "facture-ressource-1",
"method": "ressources/lecture",
"paramètres": {
"uri": "texttree://invoices/'"$INVOICE_ID"'"
    }
  }'
```

Les charges utiles d'élicitation en mode URL incluent `mode: "url"`, un `kind`, un
`correlation_id`, un `status_uri`, un `url` hébergé, un `prompt` lisible par l'homme,
`expires_at` et `status: "pending"`. Traite l'URL comme un transfert d'action à l'utilisateur ;
ne traitez pas les résultats du modèle uniquement comme une approbation de financement, un consentement ou
fourniture de numéros. Les agents peuvent reprendre en interrogeant `status_uri` :

```bash
boucle https://api.texttree.ai/mcp \
-H "Autorisation : Porteur $TEXTREE_ACCESS_TOKEN" \
-H "Accepter : application/json, text/event-stream" \
-H "Type de contenu : application/json" \
-d '{
"jsonrpc": "2.0",
"id": "ressource-élicitation-1",
"method": "ressources/lecture",
"paramètres": {
"uri": "texttree://elicitations/'"$CORRELATION_ID"'"
    }
  }'
```

La ressource d'élicitation est limitée à l'utilisateur actuel de TextTree. ID de corrélation
inconnu ou d'un autre utilisateur renvoie `resource_not_found` ; transferts en attente
à `expired` après son horodatage `expires_at`.

### 5. Soumettre la première production SMS

Une fois l'espace de travail financé et, pour le chemin recommandé, le nombre
dédié est connecté, envoyez en utilisant `tools/call` avec `messages.send` ou
le point de terminaison de messagerie V1 normal. Les deux routes utilisent les mêmes suppression, flux et
idempotence, préparation de l'expéditeur et du livreur.

Appel à l'outil MCP :

```bash
boucle https://api.texttree.ai/mcp \
-H "Autorisation : Porteur $TEXTREE_ACCESS_TOKEN" \
-H "Accepter : application/json, text/event-stream" \
-H "Type de contenu : application/json" \
-d '{
"jsonrpc": "2.0",
"id": "envoyer-1",
"method": "outils/appel",
"paramètres": {
"name": "messages.envoyer",
"arguments": {
"numéro_téléphone": "+15551234567",
"body": "Merci de vous être connecté au support Acme. Répondez ici à tout moment.",
"idempotency_key": "premier-envoi-2026-06-07"
      }
    }
  }'
```

Chemin de compatibilité API V1 :

```bash
boucle https://api.texttree.ai/api/v1/messages \
-H "Autorisation : Porteur $TEXTREE_ACCESS_TOKEN" \
-H "Type de contenu : application/json" \
-d '{
"numéro_téléphone": "+15551234567",
"body": "Merci de vous être connecté au support Acme. Répondez ici à tout moment.",
"idempotency_key": "premier-envoi-2026-06-07"
  }'
```

Interrogez le message pour connaître l'état de livraison et inspectez les journaux du tableau de bord pour connaître l'état.
du fournisseur.

```bash
boucle https://api.texttree.ai/api/v1/messages/$MESSAGE_ID \
-H "Autorisation : Porteur $TEXTREE_ACCESS_TOKEN"
```

## Modèle d'intégration d'agent

Utilisez les outils MCP pour un contexte limité et des soumissions auditées. Un agent IA doit :

1. Lisez les ressources d'intégration et de facturation avant l'exécution
2. Collectez les détails explicites du destinataire, du financement, de la marque, du site Web, du stockage et de l'approbation.
3. déléguez l'approbation finale de la soumission à votre application ou à un opérateur humain si nécessaire
4. appelez `messages.send` ou envoyez en utilisant `/api/v1/messages` pour exécuter les portes de suppression, de dépenses, de préparation de l'expéditeur et de fournisseur.

Cela maintient les flux de travail des agents derrière les mêmes contrôles de production que les soumissions humaines et API.

## Récupération avec codes de sauvegarde

Les codes de sauvegarde sont renvoyés lors du démarrage du compte sans tête ou générés dans les paramètres du compte.
Ils ne sont affichés qu’une seule fois, hachés et consommés lors de la première utilisation. Générer un nouveau
set invalide les codes inutilisés existants après confirmation explicite. Les tentatives
Les messages de récupération sont limités en débit et sont enregistrés sans stocker les codes bruts.

## Restrictions actuelles de la phase alpha

- Les outils MCP restent basés sur la configuration plutôt que configurables par le locataire
- l'exécuteur par défaut est intentionnellement simple et n'est pas un environnement d'exécution dynamique complet
- il n'y a pas de visionneuse de journaux d'audit public en dehors des surfaces opérateurs Phoenix et de la base de données du référentiel