# OpenAI MCP Compatibility

Canonical URL: https://texttree.ai/docs/openai-mcp/
Markdown URL: https://texttree.ai/docs/openai-mcp.md

## Summary

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

## GEO role

Supports OpenAI-compatible MCP and Apps SDK integration questions.

## Documentation 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, prefer `messages.preview`
before `messages.send`, and only send recipient-approved SMS with a stable
idempotency key.

## Tools

The current tool registry is:

| Tool | Scope | Purpose |
| --- | --- | --- |
| `contacts.lookup` | `mcp:execute` | Look up a contact record for agent context. |
| `messages.preview` | `mcp:execute` | Preview an outbound SMS payload before execution. |
| `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, compliance, and delivery-worker gates as
`POST /api/v1/messages`.