# OpenAI MCP Compatibility

Canonical URL: https://texttree.ai/en/docs/openai-mcp/
Markdown URL: https://texttree.ai/en/docs/openai-mcp.md
Page type: docs
Translation status: approved
Legal status: not_required

## Summary

OpenAI Apps SDK and MCP compatibility details for TextTree tools, prompts, resources, schemas, and metadata.

## Source content

# OpenAI MCP Compatibility

TextTree exposes a native MCP endpoint that can be used by OpenAI-compatible MCP
clients:

```txt
https://api.texttree.ai/mcp
```

The endpoint uses stateless Streamable HTTP. Send JSON-RPC messages with
`POST /mcp`, `Authorization: Bearer $TEXTREE_ACCESS_TOKEN`, `Accept:
application/json, text/event-stream`, and `Content-Type: application/json`.
`GET /mcp` and `DELETE /mcp` return `405` because TextTree does not allocate
server-side MCP sessions.

## OAuth discovery

TextTree publishes MCP OAuth discovery metadata at:

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

OAuth clients use authorization code with PKCE S256 and the MCP resource
`https://api.texttree.ai/mcp`. Bearer tokens can be audience-bound to that MCP
resource. Audience-free tokens remain accepted for compatibility.

## Protocol versions

TextTree currently supports:

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

The server advertises capabilities for tools, prompts, resources, and
completions. `initialize` returns TextTree-specific instructions that tell
agents to read onboarding and billing resources, collect explicit real-world
targets before onboarding, and only call `messages.send` with
recipient-approved SMS and a stable idempotency key.

## JSON-RPC methods

The native MCP endpoint accepts these JSON-RPC methods:

| Method | Purpose |
| --- | --- |
| `initialize` | Starts the MCP handshake and returns the protocol version, capabilities, server info, and instructions. |
| `notifications/initialized` | Marks the client as ready after initialization. |
| `ping` | Checks endpoint liveness. |
| `tools/list` | Lists available tool descriptors. |
| `tools/call` | Executes a tool by name. |
| `resources/list` | Lists static resources. |
| `resources/templates/list` | Lists resource templates. |
| `resources/read` | Reads a resource by URI. |
| `prompts/list` | Lists available prompts. |
| `prompts/get` | Fetches a prompt by name. |
| `completion/complete` | Returns argument completions for path, sender path, and region values. |

`notifications/initialized` and other `notifications/*` messages receive no
response. As noted above, `GET /mcp` and `DELETE /mcp` return `405`.

## Tools

The current tool registry is:

| Tool | Scope | Purpose |
| --- | --- | --- |
| `messages.send` | `messages:write` | Queue an outbound SMS through the same messaging path as `/api/v1/messages`. |
| `onboarding.status` | `onboarding:read` | Inspect onboarding, balance, invoice, and SMS readiness state. |
| `onboarding.create_invoice` | `onboarding:write` | Create or reuse a launch funding invoice. |
| `onboarding.invoice_status` | `onboarding:read` | Check funding invoice status. |
| `onboarding.test_sms` | `onboarding:write` | Send the fixed Fast Send onboarding test SMS. |
| `onboarding.request_dedicated_number` | `onboarding:write` | Submit business details for the recommended Dedicated Number path. |

Tool calls through native MCP require `mcp:execute` plus any tool-specific scope.
The legacy REST route `POST /mcp/tools/:name` also requires `mcp:execute` plus
the tool-specific scope.

## Tool descriptor structure

`tools/list` returns descriptors with:

- `name`, `title`, and `description`
- JSON Schema 2020-12 `inputSchema`
- JSON Schema 2020-12 `outputSchema`
- MCP annotations: `readOnlyHint`, `destructiveHint`, `idempotentHint`, and
  `openWorldHint`
- `_meta["texttree/required_scope"]`
- `_meta["texttree/timeout_ms"]`

OpenAI Apps SDK UI widget fields are not currently provided. TextTree does not
ship an Apps SDK web component, so descriptors do not include
`_meta.ui.resourceUri` or `_meta["openai/outputTemplate"]`. If TextTree adds a
ChatGPT app UI later, those fields should point to the UI template resource and
the descriptors should mirror any `securitySchemes` needed by older clients.

## Prompts

Current MCP prompts:

- `texttree.onboard_agent`
  - arguments: `path` (`dedicated_number` or `fast_send`), `region`
  - purpose: guide an agent through Dedicated Number or Fast Send onboarding
- `texttree.first_send`
  - arguments: `recipient_context`, `sender_path` (`dedicated_number` or
    `fast_send`)
  - purpose: prepare a safe first SMS send after onboarding and funding

Prompt completions are available for path, sender path, and region arguments.

## Resources and templates

Current resources:

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

Current resource templates:

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

Resource reads enforce their resource-specific TextTree scopes before returning
data.

## Safety model

`messages.send` is the only current MCP tool that queues an outbound SMS. It is
marked as destructive and open-world, requires `messages:write`, and runs
through the same suppression, spend, sender-readiness, and delivery-worker gates as
`POST /api/v1/messages`.