MCP

Direkte Antwort

Aktuelle MCP-Routen, -Bereiche, Ausführungs-Wrapper und Laufzeitsteuerungen.

Seiteninhalt

# MCP

TextTree stellt eine begrenzte MCP-Oberfläche für die Erkennung und kontrollierte Ausführung von Tools bereit.

## Basisrouten

- `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`

Die lokale Entwicklung mit Phoenix läuft auf `http://localhost:4001`.

`POST /mcp` ist der native MCP-JSON-RPC-Endpunkt. Die `/mcp/tools`-Pfade sind
Kompatible REST-Routen für bestehende TextTree-Integrationen und zum Debuggen.
TextTree arbeitet derzeit mit Streamable Stateless HTTP: Es werden JSON-RPC-Nachrichten gesendet
mit `POST /mcp`. SSE `GET /mcp` Flow Probes und Sitzungsbeendigungsanfragen
`DELETE /mcp` gibt `405 Method Not Allowed` zurück, da keine MCP-Sitzung zugewiesen ist
auf der Serverseite.

## Discovery-Metadaten

TextTree veröffentlicht MCP-Autorisierungserkennungsmetadaten für MCP-HTTP-Clients:

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

Nicht authentifizierte MCP-Anfragen geben `401` mit einer `WWW-Authenticate`-Herausforderung zurück
Dies verweist auf die Metadaten-URL der geschützten Ressource. Autorisierungsmetadaten
kündigen Unterstützung für Client-ID-Metadatendokumente, dynamische Client-Registrierung,
Autorisierungscode-Gewährung, PKCE S256 und öffentlicher Client-Token-Austausch für Kunden
MCP HTTP. TextTree unterstützt auch weiterhin das Bootstrapping erstklassiger Inhabertokens
Teil über `POST /mcp/accounts`. Die abwärtskompatible Route
`POST /api/v1/onboarding/api-key` stellt jetzt Inhaberzugriffstoken `txt_...` aus
die MCP und die Entwickler-API verwenden.

MCP-Client-Flow mit OAuth:

1. Bevorzugen Sie ein Client-ID-Metadatendokument: Legen Sie `client_id` als HTTPS-URL fest
   Hosten Sie die Client-Metadaten JSON. Verwenden Sie `POST /oauth/register` nur als
   Dynamische Registrierungsalternative für Clients, die keine Metadaten hosten können.
2. Senden Sie den Benutzer mit `response_type=code` an `GET /oauth/authorize`.
   `client_id`, `redirect_uri`, `resource=https://api.texttree.ai/mcp`,
   `code_challenge` und `code_challenge_method=S256`.
3. TextTree zeigt im Browser einen Einwilligungsbildschirm mit dem MCP-Client, dem Umleitungs-URI,
   die angeforderte Ressource und der Umfang. Genehmigung sendet `POST /oauth/authorize` und
   mit `code` zurückleiten; Ablehnung leitet zurück mit `error=access_denied`.
4. Tauschen Sie den in `POST /oauth/token` zurückgegebenen Code gegen den aus
   entsprechendes `code_verifier` und der gleiche Wert von `resource`. JSON-Anfragen werden akzeptiert und
   `application/x-www-form-urlencoded`.
5. Verwenden Sie das in `POST /mcp` zurückgegebene TextTree-Bearer-Token.
6. Widerrufen Sie ein in Ihrem Besitz befindliches Bearer-Token mit `POST /oauth/revoke` beim MCP-Client
   Melden Sie sich ab oder ändern Sie Ihre Anmeldeinformationen.

Beispiel eines Client-ID-Metadatendokuments:

```json
{
  „client_id“: „https://agent.example.com/.well-known/oauth-client.json",
  „client_name“: „Beispielagent“,
  „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“: „none“
}
```

Wenn TextTree während der Autorisierung ein URL-formatiertes `client_id` sieht, erhält es
und validieren Sie dieses Dokument, bevor Sie Ihre Einwilligung erteilen. Die Dokument-URL muss verwendet werden
HTTPS auf dem Standardport, darf keine Anmeldeinformationen oder ein Fragment enthalten und muss
Nur zu öffentlichen IP-Adressen auflösen. Hostet localhost, privat, Link-Local, Multicast
und ungelöste Probleme werden vor Erhalt abgelehnt. Der erhaltene JSON muss a enthalten
`client_id`, das genau mit der URL übereinstimmt, ein `client_name`, mindestens eines
unterstützten Bereich und das angeforderte `redirect_uri`. Wenn `grant_types` oder
`response_types` vorhanden sind, müssen sie `authorization_code` und `code` enthalten.
TextTree speichert gültige Metadaten gemäß `Cache-Control: max-age` oder zwischen
`Expires`; `no-cache` und `no-store` erzwingen beim nächsten Mal eine erneute Validierung
Autorisierungsanfrage. Dokumente ohne Cache-Header verwenden ein Cache-Fenster
Der Standardwert ist kurz und TextTree begrenzt die Lebensdauer des Metadatencaches auf einen Tag.

TextTree-Inhabertoken können an die MCP-Ressource zielgruppengebunden sein. Die neuen MCP-Tokens
Der vom Betreiber ausgegebene Code muss die kanonische URL der MCP-Ressource verwenden
Zielgruppe, zum Beispiel `https://api.texttree.ai/mcp`. Tokens ohne Publikum werden fortgesetzt
wird aus Kompatibilitätsgründen akzeptiert, ein publikumsgebundenes Token wird jedoch bei Verwendung abgelehnt
gegen eine andere TextTree-Ressource.

Der OAuth-Wert `resource` ist auf die URL der MCP-Ressource beschränkt. Die Bereiche
Nicht unterstützte angeforderte Anforderungen schlagen mit `invalid_scope` fehl, anstatt zu erweitern
oder stillschweigend reduzieren.

Autorisierte OAuth-MCP-Clients können über die API aufgelistet und widerrufen werden:

```bash
Curl https://api.texttree.ai/oauth/revoke \
  -H „Inhaltstyp: application/x-www-form-urlencoded“ \
  -d „token=$TEXTREE_ACCESS_TOKEN&token_type_hint=access_token“

Locken https://api.texttree.ai/api/v1/mcp/oauth-clients \
  -H „Autorisierung: Inhaber $TEXTREE_ACCESS_TOKEN“

curl -X DELETE https://api.texttree.ai/api/v1/mcp/oauth-clients/mcp_client_... \
  -H „Autorisierung: Inhaber $TEXTREE_ACCESS_TOKEN“
```

`POST /oauth/revoke` folgt der OAuth-Widerrufskonvention und gibt `200` zurück
für unbekannte Token, damit Anrufer die Existenz von Token nicht preisgeben.
Für die Liste ist `mcp:read` erforderlich. Der Widerruf erfordert `mcp:execute` und widerruft
die aktiven TextTree-Bearer-Tokens, die über diesen OAuth-MCP-Client für ausgegeben wurden
aktueller Benutzer.

`POST /oauth/register` und `POST /oauth/token` haben Ratenbegrenzungen pro Client-IP.
Ratenbegrenzte Anfragen geben `429` mit einem `Retry-After`-Header zurück und
`oauth_client_registration_rate_limited` oder `oauth_token_exchange_rate_limited`.
Buckets sind unabhängig, sodass Registrierungsspitzen den Token-Austausch nicht belasten
Autorisierungscode.

## Authentifizierung und Bereiche

Authentifizierte MCP-Anfragen verwenden von TextTree ausgegebene Bearer-Token. Die Menschen, die Benutzer
Wallet- und KI-Agenten präsentieren den gleichen `Authorization: Bearer <token>`-Header
nach der Authentifizierung über TextTree.

KI-Agenten können mithilfe von `POST /mcp/accounts` ihre eigene TextTree-Identität booten
mit Benutzername und Passwort. Für diese Route ist keine Authentifizierung erforderlich, sie gibt Codes zurück
Backup plus ein TextTree-Bearer-Token und ist auf die erfolgreiche Kontoerstellung beschränkt
pro IP-Adresse alle fünf Minuten.

Die aktuellen Bereiche auf Routenebene sind:

- `POST /mcp` akzeptiert `initialize` und `ping` mit jedem authentifizierten Token
- `POST /mcp` `tools/list`, `resources/list`, `resources/templates/list`, `prompts/list` und `completion/complete` erfordern `mcp:read`
- `POST /mcp` `resources/read` erfordert einen ressourcenspezifischen Bereich
- `POST /mcp` `tools/call` erfordert `mcp:execute`
- `GET /mcp/tools` erfordert `mcp:read`
- `POST /mcp/tools/:name` erfordert `mcp:execute`
- `GET /api/v1/mcp/oauth-clients` erfordert `mcp:read`
- `DELETE /api/v1/mcp/oauth-clients/:client_id` erfordert `mcp:execute`

Tool-Einträge können auch einen spezifischeren erforderlichen Bereich im Serverprotokoll deklarieren. Wenn das so ist
auftritt, protokolliert TextTree eine blockierte Ausführungsprüfung und gibt `403 insufficient_scope` zurück.

## Nativer MCP JSON-RPC

`POST /mcp`

TextTree unterstützt JSON-RPC im MCP-Stil über HTTP für Clients, die die Methoden erwarten
Standard-MCP. Der Endpunkt erfordert ein TextTree-Bearer-Token und gibt das zurück
Antwortheader `mcp-protocol-version`.
JSON-RPC-Anfrage-Wrapper müssen `jsonrpc: "2.0"` enthalten. Anforderungs-IDs müssen vorhanden sein
Zeichenfolgen oder ganze Zahlen; Explizite IDs `null` werden abgelehnt, ungültige ID-Formulare jedoch nicht
Sie wiederholen sich in den Fehlerantworten. Methodennamen müssen Zeichenfolgen sein. Anwendungs-Wrapper
sind streng: nur `jsonrpc`, `id`, `method`, `params` und das Feld werden akzeptiert
oberste Ebene reserviert durch MCP `_meta`. Jedes `_meta`-Feld muss ein JSON-Objekt sein.
Wenn die Anforderungsparameter `_meta.progressToken` enthalten, muss das Token eine Zeichenfolge oder sein
eine ganze Zahl. TextTree behandelt Fortschrittstoken derzeit als beratende Metadaten und nicht
Gibt Fortschrittsbenachrichtigungen aus.

Unterstützte Protokollversionen:

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

Während `initialize` handelt TextTree das angeforderte `params.protocolVersion` aus
wenn es unterstützt wird. Wenn eine Initialisierungsanforderung nach einer nicht unterstützten String-Version fragt,
TextTree antwortet mit der neuesten unterstützten Version, anstatt abzustürzen
der Händedruck. Für spätere Anfragen müssen Kunden die senden
Header `MCP-Protocol-Version` mit der ausgehandelten Version. Wenn kein Header vorhanden ist
Derzeit greift TextTree aus Kompatibilitätsgründen auf `2025-03-26` zurück. Versionsheader
Nicht unterstützte Protokollcodes geben entsprechend der Transportanforderung `400 Bad Request` zurück
MCP Streambares HTTP.
Falls angegeben, muss `initialize.params.protocolVersion` eine Zeichenfolge sein.
`capabilities` muss ein Objekt sein und `clientInfo` muss ein Objekt mit a sein
`name`-Kettentyp und ein optionaler `version`-Kettentyp. Unbekannte Initialisierungsparameter sind
werden abgelehnt, mit Ausnahme des von MCP reservierten Feldes `_meta`.
`ping` akzeptiert ein leeres Parameterobjekt oder `_meta`; Andere Ping-Parameter werden abgelehnt.

`POST /mcp` erfordert einen `Accept`-Header, der beide `application/json` enthält
wie `text/event-stream`, plus `Content-Type: application/json`. Strömungssonden
`GET /mcp` erfordert `text/event-stream`. Anfragen, die Antworttypen ignorieren
angekündigte Rückkehr `406 Not Acceptable`; POST-Anfragen mit einem Inhaltstyp
außer JSON geben `415 Unsupported Media Type` zurück.

Vom Browser ausgehende MCP-Transportanforderungen müssen auch die Origin-Validierung bestehen.
Anfragen ohne `Origin`-Header werden für serverseitige und CLI-MCP-Clients akzeptiert.
Wenn ein `Origin`-Header vorhanden ist, muss er mit der Quelle der Anforderung übereinstimmen.
der konfigurierte Ursprung der öffentlichen App oder TextTree-Site oder ein Entwicklungsursprung
lokaler Loopback. Nicht vertrauenswürdige Browserquellen geben `403 forbidden_origin` zurück.

### Initialisieren

```bash
Locken https://api.texttree.ai/mcp \
  -H „Autorisierung: Inhaber $TEXTREE_ACCESS_TOKEN“ \
  -H „Akzeptieren: application/json, text/event-stream“ \
  -H „Inhaltstyp: application/json“ \
  -d '{
    „jsonrpc“: „2.0“,
    „id“: „init-1“,
    „Methode“: „initialisieren“,
    "params": {
      „protocolVersion“: „2025-11-25“,
      "Fähigkeiten": {},
      „clientInfo“: {
        „name“: „Agent-Client“,
        „Version“: „0.1.0“
      }
    }
  }'
```

Bei Erfolg werden die Fähigkeiten und die Identität des Servers zurückgegeben:

```json
{
  „jsonrpc“: „2.0“,
  „id“: „init-1“,
  "Ergebnis": {
    „protocolVersion“: „2025-11-25“,
    "Fähigkeiten": {
      "Eingabeaufforderungen": {
        „listChanged“: false
      },
      "Abschlüsse": {},
      „Ressourcen“: {
        „listChanged“: false
      },
      "Werkzeuge": {
        „listChanged“: false
      }
    },
    „serverInfo“: {
      „name“: „texttree“,
      „Version“: „0.1.0“
    },
    „instructions“: „TextTree stellt geprüfte SMS-Onboarding- und Messaging-Workflows zur Verfügung …“
  }
}
```

Clients können das zurückgegebene `instructions` im Modellkontext platzieren. Die
Anweisungen fassen TextTree-spezifische Workflow-Regeln zusammen: Dediziert bevorzugen
Nummer für eine stabile Absenderidentität, Ressourcen vor dem Ausführen von Tools lesen, verwenden
`messages.send` nur mit vom Empfänger genehmigter SMS und einem `idempotency_key`
stabil und verlassen sich auf Unterdrückung, Kosten und Absendervorbereitungstore
und TextTree-Liefermitarbeiter für Produktionssendungen.

### MCP-Tools auflisten

```bash
Locken https://api.texttree.ai/mcp \
  -H „Autorisierung: Inhaber $TEXTREE_ACCESS_TOKEN“ \
  -H „Akzeptieren: application/json, text/event-stream“ \
  -H „Inhaltstyp: application/json“ \
  -d '{
    „jsonrpc“: „2.0“,
    „id“: „tools-1“,
    „Methode“: „Tools/Liste“,
    "params": {}
  }'
```

`tools/list` erfordert `mcp:read`. Jedes Tool enthält einen Titel und ein JSON-Schema `inputSchema`
2020-12, ein JSON-Schema `outputSchema` 2020-12, MCP-Sicherheitsanmerkungen
und TextTree-Metadaten für den erforderlichen Umfang und das erforderliche Zeitlimit.
`tools/list` unterstützt MCP-Cursor-Paging. Behandelt `nextCursor` als undurchsichtig und
Geben Sie es nur in der nächsten Anforderung für `tools/list` als `params.cursor` zurück. Die Anfragen
Auflistungen akzeptieren nur `cursor` und das von MCP reservierte Feld `_meta`.

### MCP-Ressourcen auflisten

```bash
Locken https://api.texttree.ai/mcp \
  -H „Autorisierung: Inhaber $TEXTREE_ACCESS_TOKEN“ \
  -H „Akzeptieren: application/json, text/event-stream“ \
  -H „Inhaltstyp: application/json“ \
  -d '{
    „jsonrpc“: „2.0“,
    „id“: „resources-1“,
    „Methode“: „Ressourcen/Liste“,
    "params": {}
  }'
```

`resources/list` erfordert `mcp:read`. Ressourcen machen schreibgeschützten Kontext verfügbar mit
Umfangsmetadaten, sodass Agenten den Status überprüfen können, ohne ein Tool ausführen zu müssen.
`resources/list` unterstützt MCP-Cursor-Paging. Behandelt `nextCursor` als undurchsichtig
und geben Sie es erst in der nächsten Anfrage für `resources/list` als `params.cursor` zurück.
Auflistungsanfragen akzeptieren nur `cursor` und das MCP-reservierte Feld `_meta`.

Aktuelle Ressourcen:

- `texttree://mcp/tools` erfordert `mcp:read`
- `texttree://onboarding/status` erfordert `onboarding:read`
- `texttree://billing/status` erfordert `onboarding:read`
- `texttree://messages/recent` erfordert `messages:write`

### MCP-Ressourcenvorlagen auflisten

```bash
Locken https://api.texttree.ai/mcp \
  -H „Autorisierung: Inhaber $TEXTREE_ACCESS_TOKEN“ \
  -H „Akzeptieren: application/json, text/event-stream“ \
  -H „Inhaltstyp: application/json“ \
  -d '{
    „jsonrpc“: „2.0“,
    „id“: „resource-templates-1“,
    „Methode“: „Ressourcen/Vorlagen/Liste“,
    "params": {}
  }'
```

`resources/templates/list` erfordert `mcp:read` und gibt Ressourcenvorlagen zurück
Sicher durch ID für Agentenabfrage:

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

Unterstützt denselben Cursor-Paging-Vertrag wie die anderen Auflistungsmethoden und
akzeptiert nur `cursor` plus das von MCP reservierte `_meta`-Feld.

### Eine MCP-Ressource lesen

```bash
Curl https://api.texttree.ai/mcp \
  -H „Autorisierung: Inhaber $TEXTREE_ACCESS_TOKEN“ \
  -H „Akzeptieren: application/json, text/event-stream“ \
  -H „Inhaltstyp: application/json“ \
  -d '{
    „jsonrpc“: „2.0“,
    „id“: „resource-read-1“,
    „Methode“: „Ressourcen/Lesen“,
    "params": {
      „uri“: „texttree://onboarding/status“
    }
  }'
```

`resources/read` gibt JSON-Inhalt im MCP-Array `contents` zurück. Die Lesungen
Ressourcenmanager wenden den ressourcenspezifischen TextTree-Bereich an, bevor sie Daten zurückgeben.
`texttree://messages/recent` und `texttree://messages/{id}` ignorieren Telefonnummern
und die Nachrichtentexte; Verwenden Sie sie für den Lieferstatuskontext, nicht für private Inhalte
des Empfängers. `texttree://numbers/{id}` verbirgt die vollständige Telefonnummer und gibt sie zurück
Status, Nutzung, Funktionen und Compliance-Status. Alle Lesevorgänge nach ID sind auf die beschränkt
aktueller TextTree-Benutzer oder Arbeitsbereich. `texttree://elicitations/{correlation_id}`
gibt den fortsetzbaren Status einer Übertragung im Finanzierungs-, Zustimmungs- oder Konfigurations-URL-Modus zurück
der Zahl.

### MCP-Eingabeaufforderungen auflisten

```bash
Locken https://api.texttree.ai/mcp \
  -H „Autorisierung: Inhaber $TEXTREE_ACCESS_TOKEN“ \
  -H „Akzeptieren: application/json, text/event-stream“ \
  -H „Inhaltstyp: application/json“ \
  -d '{
    „jsonrpc“: „2.0“,
    „id“: „prompts-1“,
    „Methode“: „Eingabeaufforderungen/Liste“,
    "params": {}
  }'
```

`prompts/list` erfordert `mcp:read`. Prompts packen gängige TextTree-Workflows
in wiederverwendbaren Anleitungen für Agenten.
`prompts/list` unterstützt MCP-Cursor-Paging. Behandelt `nextCursor` als undurchsichtig und
Geben Sie es nur in der nächsten Anforderung für `prompts/list` als `params.cursor` zurück. Die Anfragen
Listendokumente akzeptieren nur `cursor` und das von MCP reservierte Feld `_meta`.

Aktuelle Aufforderungen:

- `texttree.onboard_agent` akzeptiert optional `path` (`dedicated_number` oder
  `fast_send`), `region`, `brand_name`, `website`, `funding_amount_cents`,
  `payment_method`, `recipient_phone_number`, `secret_storage` und
  `execution_policy`
- `texttree.first_send` akzeptiert optional `sender_path` (`dedicated_number` oder
  `fast_send`) und eine optionale Zeichenfolge `recipient_context`

Schnelle Argumente sind streng. Unbekannte Argumentnamen, falsche Typen und Werte
Eine ungültige Absenderpfad-Enumeration gibt `-32602 Invalid params` zurück.

### Holen Sie sich eine MCP-Eingabeaufforderung

```bash
Curl https://api.texttree.ai/mcp \
  -H „Autorisierung: Inhaber $TEXTREE_ACCESS_TOKEN“ \
  -H „Akzeptieren: application/json, text/event-stream“ \
  -H „Inhaltstyp: application/json“ \
  -d '{
    „jsonrpc“: „2.0“,
    „id“: „prompt-1“,
    „Methode“: „prompts/get“,
    "params": {
      „name“: „texttree.onboard_agent“,
      „Argumente“: {
        „Pfad“: „dedizierte_Nummer“,
        „Region“: „USA“
      }
    }
  }'
```

Prompt-Antworten geben `messages` vom MCP zurück, das ein Client in den Kontext einfügen kann
des Modells vor dem Aufrufen von Ressourcen oder Werkzeugen.

### Vervollständigen Sie die Argumente der MCP-Eingabeaufforderung

```bash
Curl https://api.texttree.ai/mcp \
  -H „Autorisierung: Inhaber $TEXTREE_ACCESS_TOKEN“ \
  -H „Akzeptieren: application/json, text/event-stream“ \
  -H „Inhaltstyp: application/json“ \
  -d '{
    „jsonrpc“: „2.0“,
    „id“: „complete-1“,
    „Methode“: „Abschluss/vollständig“,
    "params": {
      "ref": {
        „type“: „ref/prompt“,
        „name“: „texttree.onboard_agent“
      },
      „Argument“: {
        „Name“: „Pfad“,
        „Wert“: „d“
      }
    }
  }'
```

`completion/complete` erfordert `mcp:read` und gibt nicht sensible Hinweise zurück
für TextTree-Eingabeaufforderungsargumente. Aktuelle Fertigstellungen umfassen `path`,
`sender_path` und `region`. Freiformargumente geben eine Vervollständigungsliste zurück
leer. TextTree stellt keine Ressourcenvorlagen zur Verfügung, also Abschlussanforderungen
der Ressourcenvorlagen geben `-32602 Invalid params` zurück.

### Rufen Sie ein MCP-Tool auf

```bash
Curl https://api.texttree.ai/mcp \
  -H „Autorisierung: Inhaber $TEXTREE_ACCESS_TOKEN“ \
  -H „Akzeptieren: application/json, text/event-stream“ \
  -H „Inhaltstyp: application/json“ \
  -d '{
    „jsonrpc“: „2.0“,
    „id“: „call-1“,
    „Methode“: „Tools/Aufruf“,
    "params": {
      „name“: „onboarding.status“,
      "Argumente": {}
    }
  }'
```

`tools/call` erfordert `mcp:execute` plus den in deklarierten spezifischen Werkzeugbereich
der Rekord. Zu den Ergebnissen gehören MCP `content`, `structuredContent`, `isError`,
`_meta` von MCP und dem TextTree-Ausführungs-Audit-Wrapper. Die Ladung
`structuredContent` entspricht dem angekündigten `outputSchema` jedes Tools.
Das `_meta` des Ergebnisses des Tool-Aufrufs enthält sichere Korrelationsfelder:
`texttree/execution_id`, `texttree/tool`, `texttree/outcome` und
`texttree/is_error`. Die gleichen Metadaten sind unten enthalten
`structuredContent._meta`, sodass der angekündigte `outputSchema` mit der Last übereinstimmt
maschinenlesbares Ergebnis. Enthält keine Telefonnummern oder Körper von
Nachrichten.

TextTree validiert bekannte Toolargumente anhand des angekündigten `inputSchema`
jedes Werkzeugs vor der Ausführung. Fehlende Pflichtfelder, unbekannte Felder, Typen
Falsche, ungültige Enum-Werte und Mindestverstöße geben „-32602 Ungültig“ zurück
params` ohne das Tool auszuführen.
Die Parameter der JSON-RPC-Methoden sind ebenfalls streng: `prompts/get`, `resources/read` und
`tools/call` lehnt unbekannte Parameter der obersten Ebene ab und akzeptiert das Feld `_meta`
reserviert für MCP. Der `_meta` des Tool-Aufrufs wird als an den Executor-Kontext übergeben
Seitenkanal-MCP-Metadaten und werden nicht mit `arguments` des Tools zusammengeführt.
Wenn `_meta.progressToken` vorhanden ist, muss es eine Zeichenfolge oder eine Ganzzahl sein.
Bei den Nachrichtentools `arguments.metadata` handelt es sich um separate Metadaten, die Eigentum des Anrufers sind und können
enthalten beliebige JSON-Objektfelder zur Korrelation.

`messages.send` ist ein echtes MCP-Tool. Es wird über dieselbe Nachrichtenroute in die Warteschlange gestellt
von TextTree als `POST /api/v1/messages`, einschließlich der Unterdrückung, Ausgabe und
Lieferarbeiter. Ihre MCP-Notizen kennzeichnen sie als destruktiv und
offene Welt, weil es eine ausgehende SMS in die Warteschlange stellen und den Kontostand verbrauchen kann.

JSON-RPC-Fehler verwenden Standard-Antwort-Wrapper im MCP-Stil und bleiben erhalten
TextTree-Sicherheitsdetails in `error.data`, einschließlich `required_scope`,
`quota_exceeded`, `tool_not_allowed`, das Ausführungszeitlimit und die Überwachungsdaten wann
sind verfügbar.

### Stapel und Benachrichtigungen

JSON-RPC-Bundles werden nur akzeptiert, wenn die effektive Protokollversion die ist
Kompatibilitätsversion `2025-03-26`. Spätere Revisionen von MCP entfernten Batch-Nachrichten
des Protokollschemas, sodass Clients `2025-06-18` oder aushandeln
`2025-11-25` muss für jedes `POST /mcp` eine JSON-RPC-Nachricht senden; Losarrangements in
Diese Versionen geben `-32600 Invalid Request` zurück, wobei `error.data.error` auf gesetzt ist
`batch_not_supported`.

Für Kompatibilitätspakete `2025-03-26` gibt TextTree ein Antwortobjekt für zurück
Anfrage und ignoriert Antworten für Benachrichtigungen und JSON-RPC-Antwortnachrichten.
Nur-Benachrichtigungs- und Nur-Antwort-Batches geben `202` mit einem leeren Textkörper zurück.
Derzeit initiiert TextTree keine Server-zu-Client-Anfragen, also keine Nachrichten von
Kundenantworten werden als Nulltransporteinträge akzeptiert, wenn sie eine enthalten
`id` gültige Zeichenfolge oder Ganzzahl. Ergebnisantwortnachrichten müssen ein `result` enthalten
vom Typ Objekt; Fehlerantwortnachrichten sollten ein `error` vom Typ Objekt mit einem `code` enthalten
Ganzzahl und ein `message` vom Typ Zeichenfolge. Sendet `initialize` als separate Anfrage; ja
in einem Stapel erscheint, gibt TextTree `-32600 Invalid Request` für dieses Element zurück
des Loses. Kompatibilitätspakete sind auf 100 Artikel begrenzt; größere Lose geben a zurück
Nur Antwort `-32600 Invalid Request` mit `error.data.error` auf gesetzt
`batch_too_large`.
Methoden im `notifications/`-Namespace werden als Typbenachrichtigungen behandelt
Feuern und vergessen und niemals JSON-RPC-Antworten erhalten. TextTree ist derzeit aktiv
`notifications/initialized` und akzeptieren Stornierungsmitteilungen als Empfehlung;
Unbekannte Benachrichtigungsnamen werden ignoriert. Gewöhnliche Anfragemethoden wie
ZXPROT312QX Z, `tools/list` und `tools/call` müssen ein `id` enthalten.

```bash
Curl https://api.texttree.ai/mcp \
  -H „Autorisierung: Inhaber $TEXTREE_ACCESS_TOKEN“ \
  -H „Akzeptieren: application/json, text/event-stream“ \
  -H „Inhaltstyp: application/json“ \
  -d '[
    {
      „jsonrpc“: „2.0“,
      „id“: „ping-1“,
      „Methode“: „ping“,
      "params": {}
    },
    {
      „jsonrpc“: „2.0“,
      „Methode“: „Benachrichtigungen/initialisiert“,
      "params": {}
    },
    {
      „jsonrpc“: „2.0“,
      „id“: „tools-1“,
      „Methode“: „Tools/Liste“,
      "params": {}
    }
  ]'
```

### Kompatibilitätsrauchtest

Für einen laufenden Phoenix-Server enthält TextTree eine Kompatibilitätsrauchtestaufgabe
durchläuft den nativen MCP-Endpunkt über initialize, die initialisierte Benachrichtigung,
Tools, Ressourcen, Eingabeaufforderungen und ein Aufruf des Onboarding-Status-Tools.

```bash
CD Apps/Web
TEXTREE_ACCESS_TOKEN=txt_... mix textree.mcp.smoke --url http://localhost:4001/mcp
mix textree.mcp.smoke --url http://localhost:4001/mcp --bootstrap-local-token
```

Das Token muss `mcp:read`, `mcp:execute` und `onboarding:read` enthalten.
Übergeben Sie `--skip-execute`, um den Aufruf des Onboarding-Statustools bei der Validierung zu überspringen
ein schreibgeschütztes Token. `--bootstrap-local-token` erstellt ein einstündiges Token im
aktuelle lokale Datenbank und wird für andere MCP-URLs als localhost abgelehnt.

Binden Sie für vom Netzbetreiber ausgestellte Inhabertokens das Token an die MCP-Ressource:

```bash
mix textree.auth.issue_token agent@example.com \
  --scopes mcp:read,mcp:execute,onboarding:read,messages:write \
  --audience https://api.texttree.ai/mcp
```

## Werkzeuge auflisten

`GET /mcp/tools`

```bash
Curl https://api.texttree.ai/mcp/tools \
  -H „Autorisierung: Inhaber $TEXTREE_ACCESS_TOKEN“
```

Bei Erfolg wird eine von der Registrierung unterstützte Liste von Tools zurückgegeben:

```json
{
  „Werkzeuge“: [
    {
      „name“: „messages.send“,
      „description“: „Lösen Sie den Versand einer Nachricht über die MCP-Oberfläche aus.“,
      „required_scope“: „messages:write“,
      „timeout_ms“: 1000
    },
    {
      „name“: „onboarding.status“,
      „description“: „Token-, Kontostand-, Rechnungs- und SMS-Onboarding-Status prüfen.“,
      „required_scope“: „onboarding:read“,
      „timeout_ms“: 1000
    },
    {
      „name“: „onboarding.create_invoice“,
      „description“: „Eine Finanzierungsrechnung für den Start erstellen oder wiederverwenden.“,
      „required_scope“: „onboarding:write“,
      „timeout_ms“: 1000
    },
    {
      „name“: „onboarding.invoice_status“,
      „description“: „Finanzierungsrechnungsstatus für programmatisches Onboarding prüfen.“,
      „required_scope“: „onboarding:read“,
      „timeout_ms“: 1000
    },
    {
      „name“: „onboarding.test_sms“,
      „description“: „Senden Sie die feste Fast Send-Onboarding-Test-SMS.“,
      „required_scope“: „onboarding:write“,
      „timeout_ms“: 1000
    },
    {
      „name“: „onboarding.request_dedicated_number“,
      „description“: „Geschäftsdetails für den empfohlenen dedizierten Nummernpfad übermitteln.“,
      „required_scope“: „onboarding:write“,
      „timeout_ms“: 1000
    }
  ]
}
```

Der aktuelle Alpha-Datensatz wird serverseitig konfiguriert. Es gibt keine Oberfläche der öffentlichen Verwaltung, die verändert werden könnte
das Protokoll zur Laufzeit.

## Erstellen Sie ein Headless-Konto

`POST /mcp/accounts`

Verwenden Sie diese Route, wenn ein KI-Client ein Konto und keinen Token-Inhaber benötigt
E-Mail, Google OAuth oder Wallet-Authentifizierung.

```bash
Curl https://api.texttree.ai/mcp/accounts \
  -H „Inhaltstyp: application/json“ \
  -d '{
    "Konto": {
      „Benutzername“: „Agent-Demo“,
      „Passwort“: „Korrekte Pferdebatterieklammer“
    }
  }'
```

Bei Erfolg werden der öffentliche Benutzername, einmalige Sicherungscodes und ein Inhabertoken zurückgegeben:

```json
{
  "Konto": {
    „id“: „9d7d9df7-58a0-4716-b82e-7ad5e73f7b36“,
    „Benutzername“: „agent-demo“
  },
  „backup_codes“: [„YYYY-BBBB-CCCC-DDDD“],
  „Token“: {
    „Typ“: „Träger“,
    „access_token“: „txt_…“,
    "Bereiche": [
      „Nachrichten:schreiben“,
      „mcp:read“,
      „mcp:execute“,
      „Kampagnen:lesen“,
      „Kampagnen:schreiben“,
      „Zahlen:lesen“,
      „Zahlen:schreiben“,
      „onboarding:read“,
      „onboarding:schreiben“
    ],
    „expires_at“: „2026-06-03T15:30:00Z“
  }
}
```

Speichern Sie den Token und die Backup-Codes sofort. TextTree gibt das nicht zurück
interne synthetische E-Mail, Token-Hash, Roh-IP oder IP-Hash. Validierungsfehler
return `422 validation_failed`; die erfolgreiche und wiederholte Erstellung von Konten aus dem
Dieselbe IP innerhalb von fünf Minuten gibt `429 account_creation_rate_limited` zurück.

Nicht-Schnittstellen-Kontotoken enthalten einen `expires_at`-Wert. Agentenintegrationen
Dauerhafte Token müssen einen vom Betreiber ausgegebenen Token mit einer nützlichen Lebensdauer und Zielgruppe verwenden
Absichtlich sein oder einen Token-Neuausgabe- und Rotationsplan enthalten. Nein
speichert rohe Bearer-Tokens und Backup-Codes in Protokollen, Shell-Verlauf und Dateien
im Repository festgeschrieben.

## Sichere MCP-Onboarding-Eingabeaufforderung

Verwenden Sie eine Eingabeaufforderung mit expliziten realen Zielen und Genehmigungsgrenzen, bevor Sie a
Agentenstartkonfiguration:

```txt
Richten Sie TextTree.ai SMS für meinen KI-Agenten mit https://texttree.ai/docs/mcp/. ein
Kontoanmeldeinformationen automatisch generieren; Registrieren Sie die dedizierte Nummer unter der Marke
„AlphaGrowth“ / https://alphagrowth.io/ (USA). Speichern Sie die Token- und Backup-Codes
in einer gitignored .env. Erstellen Sie eine Finanzierungsrechnung über 100 USDC und geben Sie mir die
Anzahlungsdetails zur Zahlung; Versuchen Sie nicht, selbst zu bezahlen. Sobald die Finanzierung erfolgt ist, senden Sie eine
Testen Sie die SMS an +1XXXXXXXXXX und zeigen Sie mir, wie ich eingehende Antworten abfragen kann. Das werde ich
Ich schreibe der Nummer selbst eine SMS, um den eingehenden Anruf zu testen. Speichern Sie dann die zugewiesene Nummer, API-Basis
URL, Token-Speicherort und MCP verbinden Schritte mit einer README-Datei und schreiben Live- und
Verspottete Bash/Curl-Testskripte zum Senden und Empfangen. Halten Sie vorher für mein OK inne
alles, was Geld ausgibt, eine Nummer bereitstellt oder ändert oder eine SMS sendet.
```

Wenn eines der folgenden Elemente fehlt: Telefonnummer, Marke, Website, Finanzierungsmethode,
Geheimes Speicherziel oder Genehmigungslimit, sammeln Sie es, bevor Sie Tools ausführen.
Agenten sollten keine Empfängernummern erfinden, keine Zahlungen tätigen oder SMS simulieren
eingehende Anrufe, die ein menschliches Telefon erfordern.

## MCP-Onboarding-Runbook

Vom Agenten ausführbare Schritte:

1. Erstellen Sie einen Token-Träger oder wählen Sie ihn aus und speichern Sie ihn am gewünschten Geheimziel.
2. Lesen Sie `texttree://onboarding/status` und `texttree://billing/status`.
3. Rufen Sie nur nach ausdrücklicher Genehmigung `onboarding.request_dedicated_number` auf
   wenn der Markenname, die HTTPS-Website und die Region explizit angegeben sind.
4. Rufen Sie nach ausdrücklicher Genehmigung `onboarding.create_invoice` mit einem Betrag auf
   explizite und unterstützte Methode und gibt dem Menschen dann die Zahlungsdetails
   zurückgegeben.
5. Pollen Sie `onboarding.invoice_status` oder `texttree://invoices/{id}` bis zum Status
   von Zahlungsänderungen.
6. Rufen Sie nach der Genehmigung `onboarding.test_sms` oder `messages.send` mit dem auf
   die explizite Telefonnummer des Empfängers und ein stabiles `idempotency_key`.
7. Rufen Sie `/api/v1/messages/$MESSAGE_ID` oder `texttree://messages/{id}` ab, um dies herauszufinden
   den Lieferstatus.

Zahlungsschritte durch den Menschen:

1. Überprüfen Sie den Rechnungsbetrag, die Kette, den Token, die Wallet und das Ablaufdatum.
2. Bezahlen Sie die Rechnung außerhalb des Agenten.
3. Weisen Sie den Agenten an, die Abfrage fortzusetzen, nachdem die Zahlung gesendet wurde.

Schritte zum Testen menschlicher Eingaben:

1. Warten Sie, bis die zugewiesene Nummer verbunden ist.
2. Senden Sie von einem echten Telefon aus eine Textnachricht an die zugewiesene Nummer.
3. Fordert den Agenten zum Empfang von Abfragebefehlen oder Webhook-Inspektionsschritten auf.

Schritte, die einer ausdrücklichen Genehmigung bedürfen:

- Erstellen Sie eine Finanzierungsüberweisung oder eine Rechnung für eine tatsächliche Zahlung.
- Fordern Sie eine dedizierte Nummer an, stellen Sie sie bereit oder ändern Sie sie.
- Senden Sie eine beliebige SMS an eine echte Telefonnummer.
- Inhabertoken und Backup-Codes speichern oder rotieren.

## Führen Sie ein Tool aus

`POST /mcp/tools/:name`

### Anforderungstext

```json
{
  "params": {}
}
```

### locken

```bash
Curl https://api.texttree.ai/mcp/tools/onboarding.status \
  -H „Autorisierung: Inhaber $TEXTREE_ACCESS_TOKEN“ \
  -H „Inhaltstyp: application/json“ \
  -d '{"params": {}}'
```

### JavaScript

```js
const Antwort = Warten auf fetch("https://api.texttree.ai/mcp/tools/onboarding.status", {
  Methode: „POST“,
  Überschriften: {
    Autorisierung: `Bearer ${process.env.TEXTREE_ACCESS_TOKEN}`,
    „Content-Type“: „application/json“,
  },
  body: JSON.stringify({ params: {} }),
});

const { Ausführung } = Warten auf Antwort.json();
```

### Erfolgreiche Antwort

```json
{
  „Ausführung“: {
    „id“: „513f6a41-2c33-4c15-b4e2-10da14ab806f“,
    „tool“: „onboarding.status“,
    „outcome“: „erfolgreich“,
    "params_summary": {},
    „result_summary“: {
      „vollständig“: falsch,
      „product_mode“: „instant_send“
    },
    „error_message“: null,
    „duration_ms“: 3,
    „inserted_at“: „2026-04-26T21:02:15Z“
  }
}
```

## Fehlerantworten

- `403` mit `{"error":"tool_not_allowed"}`, wenn sich das Tool außerhalb der konfigurierten Zulassungsliste befindet
- `403` mit `{"error":"insufficient_scope","required_scope":"..."}`, wenn dem Token das fehlt
  Umfang auf Pfadebene oder auf Werkzeugebene
- `429` mit `{"error":"quota_exceeded"}`, wenn das Kontingentfenster pro Identität erschöpft ist
- `504` mit `{"error":"execution_timed_out"}`, wenn die Ausführung das konfigurierte Timeout überschreitet
- `422` mit `{"error":"execution_failed"}`, wenn der Executor einen Fehler zurückgibt

Alle diese Ausführungspfade geben einen `execution`-Wrapper zurück, wenn TextTree einen erstellen konnte
Audit-Protokoll.

MCP-`403 insufficient_scope`-Antworten enthalten auch eine `WWW-Authenticate`-Herausforderung
mit `error="insufficient_scope"`, dem erforderlichen `scope` und dem
Metadaten-URL der geschützten Ressource. MCP-Clients können diesen Header verwenden, um eine auszulösen
Gestufter Autorisierungsablauf und fehlender Bereich anfordern, ohne zu raten.

## Laufzeitsteuerungen

Die aktuelle MCP-Alpha-Laufzeit ist absichtlich streng:

– Die Ausführung wird durch die Bereiche der TextTree-Inhabertokens bestimmt
- Tools müssen in der Serverregistrierung vorhanden sein
- Werkzeuge müssen auch im Limit der Zulassungsliste vorhanden sein
- Ausführungen werden mit Akteur, Token-Identität, Tool, Parameterzusammenfassung, Ergebnis und Zeitstempel gespeichert
- Identitätsgebühren werden in einem rollierenden Fenster erhoben
- Zeitüberschreitungen pro Tool oder globale Zeitüberschreitungen stoppen lang andauernde Arbeiten
– Für die OAuth-Client-Registrierung und den Token-Austausch gelten separate Ratenlimits pro IP

OAuth-Ratenlimit-Standardwerte und Produktionsumgebungsvariablen:

- Client-Registrierung: 20 Anfragen pro IP, wird alle 60 Sekunden neu geladen
  `TEXTREE_OAUTH_CLIENT_REGISTRATION_RATE_LIMIT_CAPACITY` und
  `TEXTREE_OAUTH_CLIENT_REGISTRATION_RATE_LIMIT_REFILL_MS`
- Token-Austausch: 60 Anfragen pro IP, Aufladung alle 60 Sekunden mit
  `TEXTREE_OAUTH_TOKEN_EXCHANGE_RATE_LIMIT_CAPACITY` und
  `TEXTREE_OAUTH_TOKEN_EXCHANGE_RATE_LIMIT_REFILL_MS`

## Programmatisches Onboarding-Muster

Verwenden Sie die Onboarding-API und die MCP-Tools, um die Einrichtung abzuschließen, ohne zu raten, welches
ist der nächste Schritt. Eine dedizierte Nummer ist die empfohlene Route, wenn ein Agent eine benötigt
Persistenter Absender, den Benutzer speichern und beantworten können. Fast Send ist verfügbar
wenn das Ziel der schnellste erste ausgehende Versandtest durch Versender ist
gruppierte Schnappschüsse.

### 1. Erstellen Sie ein Token oder wählen Sie es aus

Erstellen Sie mit `POST /mcp/accounts` ein Headless-Konto oder erstellen Sie einen Token-Inhaber
von TextTree in der authentifizierten App mit den notwendigen Bereichen für Ihre Route:

- `onboarding:read` zur Überprüfung des Onboarding- und Rechnungsstatus
- `onboarding:write` zum Erstellen von Rechnungen, Testsendungen und dedizierten Nummernanfragen
- `messages:write` zum Versenden der ersten Produktions-SMS über `/api/v1/messages`
- `mcp:read` und `mcp:execute` zum Auflisten und Ausführen von MCP-Tools

Verwenden Sie für diesen Flow keinen alten API-Schlüssel `txk_...`. `POST
/api/v1/onboarding/api-key` devuelve un token bearer `txt_...` für Anrufer, die
Sie verfügen bereits über einen Token mit Onboarding-Bereich.

Vom Netzbetreiber ausgegebene Inhabertoken sollten genau den Umfang haben, den Sie benötigen
der Kunde. Für MCP-Onboarding plus Erstversand verwenden Sie:

```bash
cd apps/web && mix textree.auth.issue_token agent@example.com \
  --scopes onboarding:read,onboarding:write,mcp:read,mcp:execute,messages:write \
  --audience https://api.texttree.ai/mcp
```

Bewahren Sie die zurückgegebenen Token sofort auf. Rohe Token werden nur einmal angezeigt.

### 2. Überprüfen Sie den Onboarding-Status

Verwenden Sie die API oder das MCP-Tool, um den Token-Fortschritt, den Kontostand, die Rechnung, die Anzahl usw. zu überprüfen
die erste SMS.

```bash
Curl https://api.texttree.ai/api/v1/onboarding \
  -H „Autorisierung: Inhaber $TEXTREE_ACCESS_TOKEN“
```

```bash
Locken https://api.texttree.ai/mcp/tools/onboarding.status \
  -H „Autorisierung: Inhaber $TEXTREE_ACCESS_TOKEN“ \
  -H „Inhaltstyp: application/json“ \
  -d '{"params": {}}'
```

### 3. Wählen Sie eine Nummernroute

Empfohlen: Dedizierte Nummer. Verwenden Sie es, wenn der Agent einen stabilen Absender benötigt,
eingehende Antworten, Wiedererkennung durch Kunden oder eine Nummer, die Betreiber verwalten können. Die
Das native MCP-Tool speichert Geschäftsdetails und gibt Erhebungsmetadaten im URL-Modus zurück
die auf den von TextTree gehosteten Konfigurationsablauf verweisen.

```bash
Curl https://api.texttree.ai/mcp \
  -H „Autorisierung: Inhaber $TEXTREE_ACCESS_TOKEN“ \
  -H „Akzeptieren: application/json, text/event-stream“ \
  -H „Inhaltstyp: application/json“ \
  -d '{
    „jsonrpc“: „2.0“,
    „id“: „dedicated-number-1“,
    „Methode“: „Tools/Aufruf“,
    "params": {
      „name“: „onboarding.request_dedicated_number“,
      „Argumente“: {
        „brand_name“: „Acme-Support“,
        „website“: „https://acme.example",
        „Region“: „USA“
      }
    }
  }'
```

Schneller Versand. Verwenden Sie es für den schnellsten ersten ausgehenden Versandtest, wenn a
dedizierte Nummer. Das native MCP-Tool sendet einen festen Onboarding-Testtext
über denselben Fast Send-Testpfad wie die API.

```bash
Curl https://api.texttree.ai/mcp \
  -H „Autorisierung: Inhaber $TEXTREE_ACCESS_TOKEN“ \
  -H „Akzeptieren: application/json, text/event-stream“ \
  -H „Inhaltstyp: application/json“ \
  -d '{
    „jsonrpc“: „2.0“,
    „id“: „test-sms-1“,
    „Methode“: „Tools/Aufruf“,
    "params": {
      „name“: „onboarding.test_sms“,
      "Argumente": {
        „phone_number“: „+15551234567“
      }
    }
  }'
```

`test-sms` verwendet einen festen Onboarding-Text und kann vor der Einzahlung auf das Konto ausgeführt werden
verfügt über eine verfügbare Fast-Send-Sandbox-Zuteilung und ist ratenbegrenzt. eine Bitte
wiederholt kann `429 test_sms_rate_limited` mit `next_allowed_at` zurückgeben; danach
Verwenden Sie die mitgelieferte Sandbox-SMS und fügen Sie weiterhin Guthaben hinzu.

### 4. Finanzieren Sie den Arbeitsbereich

Erstellen oder verwenden Sie eine Startfinanzierungsrechnung mit einem Betrag, der den Anforderungen entspricht
minimales aktuelles Onboarding. Bevorzugen Sie beim Onboarding das MCP-Rechnungstool
von Agenten. The result includes elicitation metadata in URL mode with an action URL
hosted by TextTree to complete the payment.

```bash
curl https://api.texttree.ai/mcp/tools/onboarding.create_invoice \
  -H "Authorization: Bearer $TEXTREE_ACCESS_TOKEN" \
  -H „Inhaltstyp: application/json“ \
  -d '{
    "params": {
      "amount_cents": 10000,
      "payment_method": "direct_usdc"
    }
  }'
```

Poll the invoice until it becomes `paid`, `underpaid`, `expired` or
`review_required`.

```bash
curl https://api.texttree.ai/api/v1/onboarding/funding-invoices/$INVOICE_ID \
  -H "Authorization: Bearer $TEXTREE_ACCESS_TOKEN"
```

```bash
curl https://api.texttree.ai/mcp/tools/onboarding.invoice_status \
  -H "Authorization: Bearer $TEXTREE_ACCESS_TOKEN" \
  -H „Inhaltstyp: application/json“ \
  -d '{
    "params": {
      "id": "'"$INVOICE_ID"'"
    }
  }'
```

For `onboarding.invoice_status`, provide exactly one of `id` or `invoice_id`.
The resource by ID template can also be used for polling:

```bash
curl https://api.texttree.ai/mcp \
  -H "Authorization: Bearer $TEXTREE_ACCESS_TOKEN" \
  -H "Accept: application/json, text/event-stream" \
  -H „Inhaltstyp: application/json“ \
  -d '{
    "jsonrpc": "2.0",
    "id": "invoice-resource-1",
    "method": "resources/read",
    "params": {
      "uri": "texttree://invoices/'"$INVOICE_ID"'"
    }
  }'
```

URL mode elicitation payloads include `mode: "url"`, a `kind`, a
`correlation_id`, a `status_uri`, a hosted `url`, a human-readable `prompt`,
`expires_at` and `status: "pending"`. Treats the URL as a transfer of action to the user;
do not treat model output alone as funding approval, consent, or
number provisioning. Agents can resume by polling `status_uri`:

```bash
curl https://api.texttree.ai/mcp \
  -H "Authorization: Bearer $TEXTREE_ACCESS_TOKEN" \
  -H "Accept: application/json, text/event-stream" \
  -H „Inhaltstyp: application/json“ \
  -d '{
    "jsonrpc": "2.0",
    "id": "elicitation-resource-1",
    "method": "resources/read",
    "params": {
      "uri": "texttree://elicitations/'"$CORRELATION_ID"'"
    }
  }'
```

The elicitation resource is limited to the current TextTree user. Correlation IDs
unknown or from another user return `resource_not_found`; pending transfers pass
to `expired` after its `expires_at` timestamp.

### 5. Send the first production SMS

After the workspace is funded and, for the recommended path, the number
dedicated is connected, send using `tools/call` with `messages.send` or
the normal V1 messaging endpoint. Both routes use the same suppression, flow,
idempotence, preparation of the sender and delivery worker.

Call to the MCP tool:

```bash
curl https://api.texttree.ai/mcp \
  -H "Authorization: Bearer $TEXTREE_ACCESS_TOKEN" \
  -H "Accept: application/json, text/event-stream" \
  -H „Inhaltstyp: application/json“ \
  -d '{
    "jsonrpc": "2.0",
    "id": "send-1",
    "method": "tools/call",
    "params": {
      "name": "messages.send",
      "arguments": {
        „phone_number“: „+15551234567“,
        "body": "Thanks for connecting with Acme Support. Reply here any time.",
        "idempotency_key": "first-send-2026-06-07"
      }
    }
  }'
```

V1 API Compatibility Path:

```bash
curl https://api.texttree.ai/api/v1/messages \
  -H "Authorization: Bearer $TEXTREE_ACCESS_TOKEN" \
  -H „Inhaltstyp: application/json“ \
  -d '{
    „phone_number“: „+15551234567“,
    "body": "Thanks for connecting with Acme Support. Reply here any time.",
    "idempotency_key": "first-send-2026-06-07"
  }'
```

Poll the message for delivery status and inspect the dashboard logs for status
of the supplier.

```bash
curl https://api.texttree.ai/api/v1/messages/$MESSAGE_ID \
  -H "Authorization: Bearer $TEXTREE_ACCESS_TOKEN"
```

## Agent Integration Pattern

Use MCP tools for narrow context and audited submissions. An AI agent must:

1. Read onboarding and billing resources before execution
2. Collect explicit recipient, funding, brand, website, storage and approval details
3. delegate final approval of the submission to your application or a human operator when required
4. call `messages.send` or send using `/api/v1/messages` to run the suppression, spend, sender preparation, and supplier gates

This keeps agent workflows behind the same production controls as human and API submissions.

## Recovery with backup codes

Backup codes are returned during headless account startup or generated in account settings.
They are displayed only once, hashed, and consumed on first use. Generate a new
set invalidates existing unused codes upon explicit confirmation. The attempts
Recovery messages are rate-limited and are logged without storing the raw codes.

## Current alpha phase restrictions

- MCP tools remain configuration-backed rather than tenant-configurable
- the default executor is intentionally simple and is not a full tool dynamic runtime
- there is no public audit log viewer outside of the Phoenix operator surfaces and the repository database