MCP

Resposta direta

Rotas, escopos, wrappers de execução e controles de tempo de execução atuais do MCP.

Conteúdo fonte

# MCP

TextTree expõe uma superfície MCP limitada para descoberta e execução controlada de ferramentas.

## Rotas básicas

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

O desenvolvimento local com Phoenix é executado em `http://localhost:4001`.

`POST /mcp` é o endpoint JSON-RPC do MCP nativo. As rotas `/mcp/tools` são
Rotas REST de compatibilidade para integrações TextTree existentes e para depuração.
TextTree atualmente opera com Streamable Stateless HTTP: mensagens JSON-RPC são enviadas
com `POST /mcp`. Sondas de fluxo SSE `GET /mcp` e solicitações de encerramento de sessão
`DELETE /mcp` retorna `405 Method Not Allowed` porque nenhuma sessão MCP está atribuída
no lado do servidor.

## Metadados de descoberta

TextTree publica metadados de descoberta de autorização MCP para clientes HTTP MCP:

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

Solicitações MCP não autenticadas retornam `401` com um desafio `WWW-Authenticate`
que aponta para a URL de metadados do recurso protegido. Metadados de autorização
anunciar suporte para documento de metadados de ID de cliente, registro dinâmico de cliente,
concessões de código de autorização, PKCE S256 e troca de token de cliente público para clientes
MCPHTTP. TextTree também continua a oferecer suporte à inicialização de tokens ao portador de primeira classe
parte via `POST /mcp/accounts`. A rota compatível com versões anteriores
`POST /api/v1/onboarding/api-key` agora emite tokens de acesso ao portador `txt_...`
que usam o MCP e a API do desenvolvedor.

Fluxo do cliente MCP com OAuth:

1. Prefira um documento de metadados de ID do cliente: defina `client_id` como um URL HTTPS que
   hospedar o JSON dos metadados do cliente. Use `POST /oauth/register` apenas como
   alternativa de registro dinâmico para clientes que não podem hospedar metadados.
2. Envie o usuário para `GET /oauth/authorize` com `response_type=code`,
   `client_id`, `redirect_uri`, `resource=https://api.texttree.ai/mcp`,
   `code_challenge` e `code_challenge_method=S256`.
3. TextTree exibe uma tela de consentimento no navegador com o cliente MCP, o URI de redirecionamento,
   o recurso e o escopo solicitado. A aprovação envia `POST /oauth/authorize` e
   redirecionar de volta com `code`; a rejeição redireciona de volta com `error=access_denied`.
4. Troque o código retornado em `POST /oauth/token` pelo
   correspondente `code_verifier` e o mesmo valor de `resource`. Solicitações JSON são aceitas e
   `application/x-www-form-urlencoded`.
5. Use o token portador TextTree retornado em `POST /mcp`.
6. Revogue um token ao portador em sua posse com `POST /oauth/revoke` quando o cliente MCP
   saia ou alterne suas credenciais.

Exemplo de documento de metadados de ID do cliente:

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

Quando o TextTree vê um `client_id` formatado em URL durante a autorização, ele obtém
e valide esse documento antes de mostrar consentimento. O URL do documento deve usar
HTTPS na porta padrão, não deve incluir credenciais ou um fragmento e deve
resolver apenas para endereços IP públicos. Hospeda localhost, privado, link local, multicast
e não resolvidos são rejeitados antes de serem obtidos. O JSON obtido deve conter um
`client_id` que corresponda exatamente ao URL, um `client_name`, pelo menos um
faixa suportada e o `redirect_uri` solicitado. Se `grant_types` ou
`response_types` estão presentes, eles devem incluir `authorization_code` e `code`.
TextTree armazena em cache metadados válidos com base em `Cache-Control: max-age` ou
`Expires`; `no-cache` e `no-store` forçam a revalidação no próximo
solicitação de autorização. Documentos sem cabeçalhos de cache usam uma janela de cache
O padrão é curto e o TextTree limita a vida útil do cache de metadados a um dia.Os tokens portadores TextTree podem ser vinculados ao público ao recurso MCP. Os novos tokens MCP
emitido pelo operador deve usar o URL canônico do recurso MCP como
público, por exemplo `https://api.texttree.ai/mcp`. Tokens sem audiência continuam
sendo aceito para compatibilidade, mas um token vinculado ao público é rejeitado quando usado
contra um recurso TextTree diferente.

O valor OAuth `resource` está restrito à URL do recurso MCP. Os escopos
Solicitações solicitadas não suportadas falham com `invalid_scope` em vez de expandir
ou reduzir silenciosamente.

Os clientes OAuth MCP autorizados podem ser listados e revogados por meio da API:

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

curl https://api.texttree.ai/api/v1/mcp/oauth-clients \
  -H "Authorization: Bearer $TEXTREE_ACCESS_TOKEN"

curl -X DELETE https://api.texttree.ai/api/v1/mcp/oauth-clients/mcp_client_... \
  -H "Authorization: Bearer $TEXTREE_ACCESS_TOKEN"
```

`POST /oauth/revoke` segue a convenção de revogação OAuth e retorna `200`
para tokens desconhecidos, para que os chamadores não vazem a existência de tokens.
A lista requer `mcp:read`. A revogação requer `mcp:execute` e revoga
os tokens de portador TextTree ativos emitidos por meio desse cliente OAuth MCP para o
usuário atual.

`POST /oauth/register` e `POST /oauth/token` têm limites de taxa por IP do cliente.
Solicitações com taxa limitada retornam `429` com um cabeçalho `Retry-After` e
`oauth_client_registration_rate_limited` ou `oauth_token_exchange_rate_limited`.
Os buckets são independentes, portanto, os picos de registro não esgotam as trocas de tokens
código de autorização.

## Autenticação e escopos

As solicitações MCP autenticadas usam tokens de portador emitidos pelo TextTree. Os humanos, os usuários
carteira e agentes de IA apresentam o mesmo cabeçalho `Authorization: Bearer <token>`
após autenticação via TextTree.

Os agentes de IA podem inicializar sua própria identidade TextTree usando `POST /mcp/accounts`
com nome de usuário e senha. Essa rota não requer autenticação, ela retorna códigos
backup mais um token de portador TextTree e é limitado à criação de conta bem-sucedida
por endereço IP a cada cinco minutos.

Os escopos atuais no nível da rota são:

- `POST /mcp` aceita `initialize` e `ping` com qualquer token autenticado
- `POST /mcp` `tools/list`, `resources/list`, `resources/templates/list`, `prompts/list` e `completion/complete` requerem `mcp:read`
- `POST /mcp` `resources/read` requer escopo específico de recurso
- `POST /mcp` `tools/call` requer `mcp:execute`
- `GET /mcp/tools` requer `mcp:read`
- `POST /mcp/tools/:name` requer `mcp:execute`
- `GET /api/v1/mcp/oauth-clients` requer `mcp:read`
- `DELETE /api/v1/mcp/oauth-clients/:client_id` requer `mcp:execute`

As entradas da ferramenta também podem declarar um escopo necessário mais específico no log do servidor. Se isso
ocorre, o TextTree registra uma auditoria de execução bloqueada e retorna `403 insufficient_scope`.

## MCP JSON-RPC nativo

`POST /mcp`

TextTree suporta JSON-RPC estilo MCP sobre HTTP para clientes que esperam os métodos
MCP padrão. O endpoint requer um token de portador TextTree e retorna o
Cabeçalho de resposta `mcp-protocol-version`.
Os wrappers de solicitação JSON-RPC devem incluir `jsonrpc: "2.0"`. Os IDs de solicitação devem ser
strings ou inteiros; IDs `null` explícitos são rejeitados e formulários de ID inválidos não são
eles repetem nas respostas de erro. Os nomes dos métodos devem ser strings. Wrappers de aplicativos
são rigorosos: apenas `jsonrpc`, `id`, `method`, `params` e o campo são aceitos
nível superior reservado pelo MCP `_meta`. Cada campo `_meta` deve ser um objeto JSON.
Quando os parâmetros de solicitação incluem `_meta.progressToken`, o token deve ser uma string ou
um número inteiro. TextTree atualmente trata tokens de progresso como metadados consultivos e não
Emite notificações de progresso.

Versões de protocolo suportadas:

-`2025-11-25`
-`2025-06-18`
-`2025-03-26`Durante `initialize`, TextTree negocia o `params.protocolVersion` solicitado
quando é suportado. Se uma solicitação de inicialização solicitar uma versão de string não suportada,
TextTree responde com sua versão suportada mais recente em vez de travar
o aperto de mão. Para pedidos posteriores, os clientes deverão enviar o
cabeçalho `MCP-Protocol-Version` com a versão negociada. Se não houver cabeçalho
presente, TextTree recorre a `2025-03-26` para compatibilidade. Cabeçalhos de versão
Códigos de protocolo não suportados retornam `400 Bad Request`, de acordo com o requisito de transporte
HTTP streamável MCP.
Se fornecido, `initialize.params.protocolVersion` deve ser uma string,
`capabilities` deve ser um objeto e `clientInfo` deve ser um objeto com um
Tipo de corrente `name` e um tipo de corrente `version` opcional. Parâmetros de inicialização desconhecidos são
são rejeitados, exceto o campo `_meta` reservado pelo MCP.
`ping` aceita um objeto de parâmetros vazio ou `_meta`; outros parâmetros de ping são rejeitados.

`POST /mcp` requer um cabeçalho `Accept` que inclua ambos `application/json`
como `text/event-stream`, mais `Content-Type: application/json`. sondas de fluxo
`GET /mcp` requer `text/event-stream`. Solicitações que ignoram tipos de resposta
retorno anunciado `406 Not Acceptable`; Solicitações POST com um tipo de conteúdo
diferente de JSON retorna `415 Unsupported Media Type`.

As solicitações de transporte MCP originadas no navegador também devem passar pela validação de Origem.
Solicitações sem um cabeçalho `Origin` são aceitas para clientes CLI MCP e do lado do servidor.
Quando um cabeçalho `Origin` estiver presente, ele deverá corresponder à origem da solicitação,
a origem configurada do aplicativo público ou site TextTree, ou uma origem de desenvolvimento
loopback local. Fontes de navegador não confiáveis ​​retornam `403 forbidden_origin`.

### Inicializar

```bash
curl https://api.texttree.ai/mcp \
  -H "Authorization: Bearer $TEXTREE_ACCESS_TOKEN" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "init-1",
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-11-25",
      "capabilities": {},
      "clientInfo": {
        "name": "agent-client",
        "version": "0.1.0"
      }
    }
  }'
```

O sucesso retorna os recursos e a identidade do servidor:

```json
{
  "jsonrpc": "2.0",
  "id": "init-1",
  "result": {
    "protocolVersion": "2025-11-25",
    "capabilities": {
      "prompts": {
        "listChanged": false
      },
      "completions": {},
      "resources": {
        "listChanged": false
      },
      "tools": {
        "listChanged": false
      }
    },
    "serverInfo": {
      "name": "texttree",
      "version": "0.1.0"
    },
    "instructions": "TextTree exposes audited SMS onboarding and messaging workflows..."
  }
}
```

Os clientes podem colocar o `instructions` retornado no contexto do modelo. O
As instruções resumem as regras de fluxo de trabalho específicas do TextTree: Prefira Dedicado
Número para uma identidade de remetente estável, leia os recursos antes de executar as ferramentas, use
`messages.send` apenas com SMS aprovado pelo destinatário e um `idempotency_key`
estável e depende de supressão, despesas e portas de preparação do remetente
e entregador TextTree para remessas de produção.

### Listar ferramentas MCP

```bash
curl https://api.texttree.ai/mcp \
  -H "Authorization: Bearer $TEXTREE_ACCESS_TOKEN" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "tools-1",
    "method": "tools/list",
    "params": {}
  }'
```

`tools/list` requer `mcp:read`. Cada ferramenta inclui um título, um esquema JSON `inputSchema`
2020-12, um esquema JSON `outputSchema` 2020-12, anotações de segurança MCP
e metadados TextTree para escopo e tempo limite necessários.
`tools/list` suporta paginação de cursor MCP. Trata `nextCursor` como opaco e
retorne-o como `params.cursor` somente na próxima solicitação de `tools/list`. Os pedidos
as listagens aceitam apenas `cursor` e o campo `_meta` reservado pelo MCP.

### Listar recursos MCP

```bash
curl https://api.texttree.ai/mcp \
  -H "Authorization: Bearer $TEXTREE_ACCESS_TOKEN" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "resources-1",
    "method": "resources/list",
    "params": {}
  }'
```

`resources/list` requer `mcp:read`. Os recursos expõem o contexto somente leitura com
metadados de escopo para que os agentes possam inspecionar o estado sem executar uma ferramenta.
`resources/list` suporta paginação de cursor MCP. Trata `nextCursor` como opaco
e retorne-o como `params.cursor` somente na próxima solicitação de `resources/list`.
As solicitações de listagem aceitam apenas `cursor` e o campo `_meta` reservado pelo MCP.

Recursos atuais:

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

### Listar modelos de recursos MCP```bash
curl https://api.texttree.ai/mcp \
  -H "Authorization: Bearer $TEXTREE_ACCESS_TOKEN" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "resource-templates-1",
    "method": "resources/templates/list",
    "params": {}
  }'
```

`resources/templates/list` requer `mcp:read` e retorna modelos de recursos
seguro por ID para pesquisa de agente:

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

Suporta o mesmo contrato de paginação de cursor que os outros métodos de listagem e
aceita apenas `cursor` mais o campo `_meta` reservado pelo MCP.

### Leia um recurso MCP

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

`resources/read` retorna conteúdo JSON na matriz MCP `contents`. As leituras
Os gerentes de recursos aplicam o escopo TextTree específico do recurso antes de retornar os dados.
`texttree://messages/recent` e `texttree://messages/{id}` ignoram números de telefone
e os corpos das mensagens; use-os para contexto de status de entrega, não para conteúdo privado
do destinatário. `texttree://numbers/{id}` oculta o número de telefone completo e retorna
status, uso, recursos e status de conformidade. Todas as leituras por ID são limitadas ao
usuário ou espaço de trabalho atual do TextTree. `texttree://elicitations/{correlation_id}`
retorna o estado recuperável de uma transferência no modo de financiamento, consentimento ou URL de configuração
de número.

### Listar prompts do MCP

```bash
curl https://api.texttree.ai/mcp \
  -H "Authorization: Bearer $TEXTREE_ACCESS_TOKEN" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "prompts-1",
    "method": "prompts/list",
    "params": {}
  }'
```

`prompts/list` requer `mcp:read`. Os prompts empacotam fluxos de trabalho comuns do TextTree
em instruções reutilizáveis para agentes.
`prompts/list` suporta paginação de cursor MCP. Trata `nextCursor` como opaco e
retorne-o como `params.cursor` somente na próxima solicitação de `prompts/list`. Os pedidos
as listagens aceitam apenas `cursor` e o campo `_meta` reservado pelo MCP.

Solicitações atuais:

- `texttree.onboard_agent` aceita opcionalmente `path` (`dedicated_number` ou
  `fast_send`), `region`, `brand_name`, `website`, `funding_amount_cents`,
  `payment_method`, `recipient_phone_number`, `secret_storage` e
  `execution_policy`
- `texttree.first_send` aceita opcionalmente `sender_path` (`dedicated_number` ou
  `fast_send`) e uma corrente opcional `recipient_context`

Os argumentos imediatos são estritos. Nomes de argumentos desconhecidos, tipos e valores incorretos
A enumeração do caminho do remetente inválida retorna `-32602 Invalid params`.

### Obtenha um prompt do MCP

```bash
curl https://api.texttree.ai/mcp \
  -H "Authorization: Bearer $TEXTREE_ACCESS_TOKEN" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "prompt-1",
    "method": "prompts/get",
    "params": {
      "name": "texttree.onboard_agent",
      "arguments": {
        "path": "dedicated_number",
        "region": "US"
      }
    }
  }'
```

As respostas de prompt retornam `messages` do MCP que um cliente pode colocar no contexto
do modelo antes de chamar recursos ou ferramentas.

### Argumentos completos do prompt do MCP

```bash
curl https://api.texttree.ai/mcp \
  -H "Authorization: Bearer $TEXTREE_ACCESS_TOKEN" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "complete-1",
    "method": "completion/complete",
    "params": {
      "ref": {
        "type": "ref/prompt",
        "name": "texttree.onboard_agent"
      },
      "argument": {
        "name": "path",
        "value": "d"
      }
    }
  }'
```

`completion/complete` requer `mcp:read` e retorna dicas não confidenciais
para argumentos de prompt do TextTree. As conclusões atuais cobrem `path`,
`sender_path` e `region`. Argumentos de formato livre retornam uma lista de conclusão
vazio. TextTree não expõe modelos de recursos, portanto, solicitações de conclusão
dos modelos de recursos retornam `-32602 Invalid params`.

### Chame uma ferramenta MCP

```bash
curl https://api.texttree.ai/mcp \
  -H "Authorization: Bearer $TEXTREE_ACCESS_TOKEN" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "call-1",
    "method": "tools/call",
    "params": {
      "name": "onboarding.status",
      "arguments": {}
    }
  }'
```

`tools/call` requer `mcp:execute` mais o escopo de ferramenta específico declarado em
o registro. Os resultados incluem `content`, `structuredContent`, `isError` do MCP,
`_meta` do MCP e do wrapper de auditoria de execução TextTree. A carga
`structuredContent` corresponde ao `outputSchema` anunciado de cada ferramenta.
O `_meta` do resultado da chamada de ferramenta contém campos de correlação seguros:
`texttree/execution_id`, `texttree/tool`, `texttree/outcome` e
`texttree/is_error`. Os mesmos metadados estão incluídos em
`structuredContent._meta` para que o `outputSchema` anunciado corresponda à carga
resultado legível por máquina. Não inclui números de telefone ou órgãos de
mensagens.

TextTree valida argumentos de ferramentas conhecidos em relação ao `inputSchema` anunciado
de cada ferramenta antes da execução.Campos obrigatórios ausentes, campos desconhecidos, tipos
valores enum incorretos e inválidos e violações mínimas retornam `-32602 Inválido
params` sem executar a ferramenta.
Os parâmetros dos métodos JSON-RPC também são rigorosos: `prompts/get`, `resources/read` e
`tools/call` rejeita parâmetros de nível superior desconhecidos, aceitando o campo `_meta`
reservado pelo MCP. O `_meta` da chamada de ferramenta é passado para o contexto do executor como
metadados MCP do canal lateral e não são mesclados com o `arguments` da ferramenta.
Se `_meta.progressToken` estiver presente, deverá ser uma string ou um número inteiro.
As ferramentas de mensagem `arguments.metadata` são metadados separados de propriedade do chamador e podem
contêm campos de objeto JSON arbitrários para correlação.

`messages.send` é uma ferramenta MCP real. Ele está na fila pela mesma rota de mensagens
de TextTree do que `POST /api/v1/messages`, incluindo a supressão, despesas e
entregador. Suas notas do MCP a marcam como destrutiva e
mundo aberto porque pode enfileirar um SMS enviado e consumir o saldo da conta.

Erros JSON-RPC usam wrappers de resposta padrão do estilo MCP e preservam
Detalhes de segurança do TextTree em `error.data`, incluindo `required_scope`,
`quota_exceeded`, `tool_not_allowed`, tempo limite de execução e dados de auditoria quando
estão disponíveis.

### Lotes e notificações

Os pacotes JSON-RPC são aceitos somente quando a versão efetiva do protocolo é a
versão de compatibilidade `2025-03-26`. Revisões posteriores do MCP removeram mensagens em lote
do esquema de protocolo, então os clientes que negociam `2025-06-18` ou
`2025-11-25` deve enviar uma mensagem JSON-RPC para cada `POST /mcp`; arranjos de lote em
essas versões retornam `-32600 Invalid Request` com `error.data.error` definido como
`batch_not_supported`.

Para pacotes de compatibilidade `2025-03-26`, TextTree retorna um objeto de resposta para
solicita e ignora respostas para notificações e mensagens de resposta JSON-RPC.
Os lotes somente de notificação e somente de resposta retornam `202` com um corpo vazio.
Atualmente o TextTree não inicia solicitações de servidor para cliente, então mensagens de
resposta do cliente são aceitas como entradas de transporte nulas quando incluem um
`id` string ou número inteiro válido. As mensagens de resposta de resultado devem incluir um `result`
do tipo objeto; mensagens de resposta de erro devem incluir um `error` do tipo objeto com um `code`
inteiro e um `message` do tipo string. Envie `initialize` como uma solicitação separada; sim
aparece em um lote, TextTree retorna `-32600 Invalid Request` para esse elemento
do lote. Os pacotes de compatibilidade são limitados a 100 itens; lotes maiores retornam um
apenas resposta `-32600 Invalid Request` com `error.data.error` definido para
`batch_too_large`.
Os métodos no namespace `notifications/` são tratados como notificações de tipo
dispare e esqueça e nunca receba respostas JSON-RPC. TextTree atualmente atua em
`notifications/initialized` e aceitar avisos de cancelamento como aviso;
Nomes de notificação desconhecidos são ignorados. Métodos de solicitação comuns como
`ping`, `tools/list` e `tools/call` devem incluir um `id`.

```bash
curl https://api.texttree.ai/mcp \
  -H "Authorization: Bearer $TEXTREE_ACCESS_TOKEN" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "jsonrpc": "2.0",
      "id": "ping-1",
      "method": "ping",
      "params": {}
    },
    {
      "jsonrpc": "2.0",
      "method": "notifications/initialized",
      "params": {}
    },
    {
      "jsonrpc": "2.0",
      "id": "tools-1",
      "method": "tools/list",
      "params": {}
    }
  ]'
```

### Teste de fumaça de compatibilidadePara um servidor Phoenix em execução, o TextTree inclui uma tarefa de teste de compatibilidade que
percorre o endpoint MCP nativo por meio de inicialização, a notificação inicializada,
ferramentas, recursos, prompts e uma chamada para a ferramenta de status de integração.

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

O token deve incluir `mcp:read`, `mcp:execute` e `onboarding:read`.
Passe `--skip-execute` para ignorar a chamada da ferramenta de status de integração ao validar
um token somente leitura. `--bootstrap-local-token` cria um token de uma hora no
banco de dados local atual e é rejeitado para URLs MCP diferentes de localhost.

Para tokens ao portador emitidos pela operadora, vincule o token ao recurso MCP:

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

## Listar ferramentas

`GET /mcp/tools`

```bash
curl https://api.texttree.ai/mcp/tools \
  -H "Authorization: Bearer $TEXTREE_ACCESS_TOKEN"
```

Success retorna uma lista de ferramentas apoiada por registro:

```json
{
  "tools": [
    {
      "name": "messages.send",
      "description": "Trigger a message send through the MCP surface.",
      "required_scope": "messages:write",
      "timeout_ms": 1000
    },
    {
      "name": "onboarding.status",
      "description": "Inspect token, balance, invoice, and SMS onboarding state.",
      "required_scope": "onboarding:read",
      "timeout_ms": 1000
    },
    {
      "name": "onboarding.create_invoice",
      "description": "Create or reuse a launch funding invoice.",
      "required_scope": "onboarding:write",
      "timeout_ms": 1000
    },
    {
      "name": "onboarding.invoice_status",
      "description": "Check funding invoice status for programmatic onboarding.",
      "required_scope": "onboarding:read",
      "timeout_ms": 1000
    },
    {
      "name": "onboarding.test_sms",
      "description": "Send the fixed Fast Send onboarding test SMS.",
      "required_scope": "onboarding:write",
      "timeout_ms": 1000
    },
    {
      "name": "onboarding.request_dedicated_number",
      "description": "Submit business details for the recommended Dedicated Number path.",
      "required_scope": "onboarding:write",
      "timeout_ms": 1000
    }
  ]
}
```

O registro alfa atual está configurado no lado do servidor. Não há superfície da administração pública para sofrer mutação
o log em tempo de execução.

## Crie uma conta sem cabeça

`POST /mcp/accounts`

Use esta rota quando um cliente de IA precisar de uma conta e portador de token sem
e-mail, Google OAuth ou autenticação de carteira.

```bash
curl https://api.texttree.ai/mcp/accounts \
  -H "Content-Type: application/json" \
  -d '{
    "account": {
      "username": "agent-demo",
      "password": "correct horse battery staple"
    }
  }'
```

Success retorna o nome de usuário público, códigos de backup únicos e um token de portador:

```json
{
  "account": {
    "id": "9d7d9df7-58a0-4716-b82e-7ad5e73f7b36",
    "username": "agent-demo"
  },
  "backup_codes": ["AAAA-BBBB-CCCC-DDDD"],
  "token": {
    "type": "Bearer",
    "access_token": "txt_...",
    "scopes": [
      "messages:write",
      "mcp:read",
      "mcp:execute",
      "campaigns:read",
      "campaigns:write",
      "numbers:read",
      "numbers:write",
      "onboarding:read",
      "onboarding:write"
    ],
    "expires_at": "2026-06-03T15:30:00Z"
  }
}
```

Salve o token e os códigos de backup imediatamente. TextTree não retorna o
e-mail sintético interno, hash de token, IP bruto ou hash de IP. Falhas de validação
retornar `422 validation_failed`; a criação bem-sucedida e repetida de contas a partir do
mesmo IP dentro de cinco minutos retorna `429 account_creation_rate_limited`.

Os tokens de conta sem interface incluem um valor `expires_at`. Integrações de agentes
Os tokens duráveis devem usar um token emitido pelo operador com vida útil e público-alvo úteis
intencional ou incluir um plano de reemissão e rotação de tokens. Não
armazena tokens de portador brutos e códigos de backup em logs, histórico de shell e arquivos
comprometido com o repositório.

## Prompt de integração seguro do MCP

Use um aviso com objetivos explícitos do mundo real e limites de aprovação antes de um
configuração de início do agente:

```txt
Set up TextTree.ai SMS for my AI agent using https://texttree.ai/docs/mcp/.
Auto-generate account credentials; register the dedicated number under brand
"AlphaGrowth" / https://alphagrowth.io/ (US). Store the token and backup codes
in a gitignored .env. Create a $100 USDC funding invoice and give me the
deposit details to pay; do not attempt payment yourself. Once funded, send a
test SMS to +1XXXXXXXXXX and show me how to poll for inbound replies; I will
text the number myself to test inbound. Then save the assigned number, API base
URL, token location, and MCP connect steps to a README, and write live and
mocked bash/curl test scripts for send and receive. Pause for my OK before
anything that spends money, provisions or changes a number, or sends an SMS.
```

Se algum dos seguintes itens estiver faltando: número de telefone, marca, site, forma de financiamento,
destino de armazenamento secreto ou limite de aprovação, colete-o antes de executar as ferramentas.
Os agentes não devem inventar números de destinatários, efetuar pagamentos ou simular SMS
chamadas recebidas que exigem um telefone de propriedade humana.

## Manual de integração do MCP

Etapas executáveis pelo agente:

1. Crie ou escolha um portador de token e armazene-o no destino de segredos solicitado.
2. Leia `texttree://onboarding/status` e `texttree://billing/status`.
3. Após aprovação explícita, ligue para `onboarding.request_dedicated_number` sozinho
   quando o nome da marca, o site HTTPS e a região são explícitos.
4. Após aprovação explícita, ligue para `onboarding.create_invoice` com um valor
   um método explícito e compatível e, em seguida, fornece ao humano os detalhes do pagamento
   voltou.
5. Pesquise `onboarding.invoice_status` ou `texttree://invoices/{id}` até o status
   de alterações de pagamento.
6. Após aprovação, ligue para `onboarding.test_sms` ou `messages.send` com o
   número de telefone explícito do destinatário e um `idempotency_key` estável.
7. Faça uma pesquisa com `/api/v1/messages/$MESSAGE_ID` ou `texttree://messages/{id}` para descobrir
   o status da entrega.

Etapas de pagamento pelo humano:

1. Verifique o valor da fatura, corrente, token, carteira e vencimento.
2. Pague a conta fora do agente.
3.Diz ao agente para retomar a pesquisa após o envio do pagamento.

Etapas de teste de entrada humana:

1. Aguarde até que o número atribuído seja conectado.
2. Envie uma mensagem de texto para o número atribuído a partir de um telefone real.
3. Solicita ao agente comandos de pesquisa de recebimento ou etapas de inspeção de webhook.

Etapas que exigem aprovação explícita:

- Crie uma transferência de financiamento ou uma fatura destinada a um pagamento real.
- Solicite, forneça ou altere um número dedicado.
- Envie qualquer SMS para um número de telefone real.
- Armazene ou gire tokens ao portador e códigos de backup.

## Execute uma ferramenta

`POST /mcp/tools/:name`

### Corpo da solicitação

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

### curl

```bash
curl https://api.texttree.ai/mcp/tools/onboarding.status \
  -H "Authorization: Bearer $TEXTREE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"params": {}}'
```

### JavaScript

```js
const response = await fetch("https://api.texttree.ai/mcp/tools/onboarding.status", {
  method: "POST",
  headers: {
    Authorization: `Bearer undefined`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ params: {} }),
});

const { execution } = await response.json();
```

### Resposta bem sucedida

```json
{
  "execution": {
    "id": "513f6a41-2c33-4c15-b4e2-10da14ab806f",
    "tool": "onboarding.status",
    "outcome": "succeeded",
    "params_summary": {},
    "result_summary": {
      "complete": false,
      "product_mode": "instant_send"
    },
    "error_message": null,
    "duration_ms": 3,
    "inserted_at": "2026-04-26T21:02:15Z"
  }
}
```

## Respostas de erro

- `403` com `{"error":"tool_not_allowed"}` quando a ferramenta está fora da lista de permissões configurada
- `403` com `{"error":"insufficient_scope","required_scope":"..."}` quando o token não possui o
  escopo no nível do caminho ou no nível da ferramenta
- `429` com `{"error":"quota_exceeded"}` quando a janela de cota por identidade se esgota
- `504` com `{"error":"execution_timed_out"}` quando a execução excede o tempo limite configurado
- `422` com `{"error":"execution_failed"}` quando o executor retorna um erro

Todos esses caminhos de execução retornam um wrapper `execution` quando o TextTree foi capaz de criar um
registro de auditoria.

As respostas do MCP `403 insufficient_scope` também incluem um desafio `WWW-Authenticate`
com `error="insufficient_scope"`, o `scope` necessário e o
URL de metadados do recurso protegido. Os clientes MCP podem usar esse cabeçalho para acionar um
Fluxo de autorização escalonado e solicitação de escopo ausente sem adivinhação.

## Controles de tempo de execução

O atual tempo de execução alfa do MCP é intencionalmente rigoroso:

- a execução é condicionada pelos escopos dos tokens portadores TextTree
- as ferramentas devem existir no registro do servidor
- as ferramentas também devem estar presentes no limite da lista de permissões
- as execuções são persistidas com ator, identidade de token, ferramenta, resumo de parâmetros, resultado e carimbo de data/hora
- As taxas de identidade são aplicadas em uma janela contínua
- tempos limite por ferramenta ou globais interrompem trabalhos de longa duração
- O registro do cliente OAuth e a troca de tokens têm limites de taxa separados por IP

Padrões de limite de taxa OAuth e variáveis de ambiente de produção:

- cadastro de cliente: 20 solicitações por IP, recarrega a cada 60 segundos com
  `TEXTREE_OAUTH_CLIENT_REGISTRATION_RATE_LIMIT_CAPACITY` e
  `TEXTREE_OAUTH_CLIENT_REGISTRATION_RATE_LIMIT_REFILL_MS`
- troca de tokens: 60 solicitações por IP, recarga a cada 60 segundos com
  `TEXTREE_OAUTH_TOKEN_EXCHANGE_RATE_LIMIT_CAPACITY` e
  `TEXTREE_OAUTH_TOKEN_EXCHANGE_RATE_LIMIT_REFILL_MS`

## Padrão de integração programática

Use a API de integração e as ferramentas MCP para concluir a configuração sem adivinhar qual delas
é o próximo passo. O Número Dedicado é a rota recomendada quando um agente precisa de um
remetente persistente que as pessoas podem salvar e responder. O Fast Send está disponível
quando o objetivo é o primeiro teste de remessa de saída mais rápido por meio dos remetentes
instantâneos agrupados.

### 1. Crie ou escolha um token

Crie uma conta headless usando `POST /mcp/accounts` ou crie um portador de token
do TextTree no app autenticado com os escopos necessários para sua rota:- `onboarding:read` para inspecionar o status de integração e fatura
- `onboarding:write` para criar faturas, testar remessas e solicitações de números dedicados
- `messages:write` para enviar o primeiro SMS de produção via `/api/v1/messages`
- `mcp:read` e `mcp:execute` para listar e executar ferramentas MCP

Não use uma chave de API herdada `txk_...` para este fluxo. `POSTAR
/api/v1/onboarding/api-key` devuelve un token bearer `txt_...` para chamadores que
Eles já possuem um token com escopo de integração.

Os tokens ao portador emitidos pela operadora devem ser criados com os escopos exatos que você precisa
o cliente. Para integração do MCP e primeiro envio, use:

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

Salve os tokens devolvidos imediatamente. Os tokens brutos são exibidos apenas uma vez.

### 2. Verifique o status de integração

Use a ferramenta API ou MCP para inspecionar o progresso do token, saldo, fatura, número e
o primeiro SMS.

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

```bash
curl https://api.texttree.ai/mcp/tools/onboarding.status \
  -H "Authorization: Bearer $TEXTREE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"params": {}}'
```

### 3. Escolha uma rota numérica

Recomendado: Número Dedicado. Use-o quando o agente precisar de um remetente estável,
respostas recebidas, reconhecimento por parte dos clientes ou um número que as operadoras possam gerenciar. O
A ferramenta MCP nativa salva detalhes do negócio e retorna metadados de elicitação no modo URL
que apontam para o fluxo de configuração hospedado pelo TextTree.

```bash
curl https://api.texttree.ai/mcp \
  -H "Authorization: Bearer $TEXTREE_ACCESS_TOKEN" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "dedicated-number-1",
    "method": "tools/call",
    "params": {
      "name": "onboarding.request_dedicated_number",
      "arguments": {
        "brand_name": "Acme Support",
        "website": "https://acme.example",
        "region": "US"
      }
    }
  }'
```

Fast Send. Use-o para o primeiro teste de envio de saída mais rápido quando um
número dedicado. A ferramenta MCP nativa envia texto de teste de integração fixo
através do mesmo caminho de teste de Fast Send da API.

```bash
curl https://api.texttree.ai/mcp \
  -H "Authorization: Bearer $TEXTREE_ACCESS_TOKEN" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "test-sms-1",
    "method": "tools/call",
    "params": {
      "name": "onboarding.test_sms",
      "arguments": {
        "phone_number": "+15551234567"
      }
    }
  }'
```

`test-sms` usa texto de integração fixo, pode ser executado antes do financiamento quando a conta
tem uma alocação disponível de Fast Send Sandbox e tem taxa limitada. um pedido
repetido pode retornar `429 test_sms_rate_limited` com `next_allowed_at`; depois disso
use o SMS sandbox incluído e continue adicionando saldo.

### 4. Financie o espaço de trabalho

Crie ou reutilize uma fatura de financiamento de lançamento com um valor que atenda aos
integração atual mínima. Prefira a ferramenta de fatura MCP durante a integração
de agentes. O resultado inclui metadados de elicitação no modo URL com um URL de ação
hospedado por TextTree para concluir o pagamento.

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

Pesquise a fatura até que ela mude para `paid`, `underpaid`, `expired` ou
`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 "Content-Type: application/json" \
  -d '{
    "params": {
      "id": "'"$INVOICE_ID"'"
    }
  }'
```

Para `onboarding.invoice_status`, forneça exatamente um de `id` ou `invoice_id`.
O modelo de recurso por ID também pode ser usado para sondagem:

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

As cargas úteis de elicitação do modo URL incluem `mode: "url"`, um `kind`, um
`correlation_id`, um `status_uri`, um `url` hospedado, um `prompt` legível por humanos,
`expires_at` e `status: "pending"`. Trata a URL como uma transferência de ação para o usuário;
não trate o resultado do modelo apenas como aprovação de financiamento, consentimento ou
provisionamento de números. Os agentes podem retomar pesquisando `status_uri`:

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

O recurso de elicitação é limitado ao usuário TextTree atual. IDs de correlação
desconhecido ou outro usuário retorna `resource_not_found`; passe de transferência pendente
para `expired` após seu carimbo de data/hora `expires_at`.

### 5. Envie o primeiro SMS de produção

Depois que o espaço de trabalho for financiado e, para o caminho recomendado, o número
dedicado está conectado, envie usando `tools/call` com `messages.send` ou
o terminal de mensagens V1 normal.Ambas as rotas usam a mesma supressão, fluxo,
idempotência, preparação do remetente e entregador.

Ligue para a ferramenta MCP:

```bash
curl https://api.texttree.ai/mcp \
  -H "Authorization: Bearer $TEXTREE_ACCESS_TOKEN" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: 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"
      }
    }
  }'
```

Caminho de compatibilidade da API V1:

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

Pesquise a mensagem quanto ao status de entrega e inspecione o status dos registros do painel
do fornecedor.

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

## Padrão de Integração de Agente

Use ferramentas MCP para contexto restrito e envios auditados. Um agente de IA deve:

1. Leia os recursos de integração e cobrança antes da execução
2. Colete detalhes explícitos do destinatário, financiamento, marca, site, armazenamento e aprovação
3. delegar a aprovação final do envio à sua aplicação ou a um operador humano, quando necessário
4. Ligue para `messages.send` ou envie via `/api/v1/messages` para executar a supressão, gastos, preparação do remetente e portas do fornecedor

Isso mantém os fluxos de trabalho dos agentes sob os mesmos controles de produção dos envios humanos e de API.

## Recuperação com códigos de backup

Os códigos de backup são retornados durante a inicialização da conta headless ou gerados nas configurações da conta.
Eles são exibidos apenas uma vez, com hash e consumidos na primeira utilização. Gerar um novo
set invalida códigos não utilizados existentes após confirmação explícita. As tentativas
As mensagens de recuperação têm taxa limitada e são registradas sem armazenar os códigos brutos.

## Restrições atuais da fase alfa

- As ferramentas MCP permanecem com suporte de configuração em vez de serem configuráveis pelo locatário
- o executor padrão é intencionalmente simples e não é um tempo de execução dinâmico completo da ferramenta
- não há visualizador de log de auditoria público fora das superfícies do operador Phoenix e do banco de dados do repositório