Telltale API

MCP server & AI tools

Telltale ships a hosted Model Context Protocol server, so an AI coding tool can read the docs, validate and push your data, run a sync, manage keys and a sandbox, and ask OWL about your account, all from the terminal. You sign in with your Telltale login (OAuth); no keys to paste.

Claude Code

bash

claude mcp add --transport http telltale https://app.telltale.pro/api/mcp
# then, inside Claude Code:
/mcp            # sign in to Telltale when prompted

Then just ask: “Integrate my store with Telltale: validate a sample of my orders export, push it to the sandbox, sync, and tell me what to fix.”

Claude.ai (web and desktop)

Settings → Connectors → Add custom connector.
URL: https://app.telltale.pro/api/mcp. Leave client id/secret blank.
Sign in to Telltale when prompted. On Team and Enterprise plans an owner adds it under Organization settings → Connectors.

Cursor, Windsurf, and other MCP clients

mcp.json

{
  "mcpServers": {
    "telltale": { "type": "http", "url": "https://app.telltale.pro/api/mcp" }
  }
}

Tools

Tool	What it does	Writes?
`verify_connection`	Who you are, which workspace is active, what is connected, data counts, sandbox state.	No · any member
`get_docs`	The full API reference as markdown, optionally one section.	No · any member
`validate_orders` / `validate_customers`	Dry-run a batch: per-row error and warning codes, no data written (the dry run is logged).	No · owner/admin
`push_orders` / `push_customers`	Write a batch (≤5,000) to the live workspace or the sandbox. All-or-nothing on any row error; idempotent on order_id / external_id. Pushing customers changes consent, so Claude confirms first.	Yes · owner/admin
`trigger_sync` / `get_sync_status`	Queue and poll an analytics recompute.	Yes (owner/admin) / No
`get_ingest_activity`	Recent batches with counts and error codes (your own order/customer ids on failed rows, never names/emails/phones).	No · any member
`list_ingest_keys` / `create_ingest_key` / `rotate_ingest_key` / `revoke_ingest_key`	Key lifecycle for your own code and CI. Secrets are shown once; listing shows prefixes only.	Yes (list is read) · owner/admin
`create_sandbox` / `reset_sandbox`	A zero-egress sandbox workspace for end-to-end testing.	Yes · owner/admin
`get_retention_briefing`	Today's retention snapshot for the workspace.	No · any member
`ask_owl`	Ask Telltale's analyst about your customers, metrics, campaigns, integrations (uses OWL credits).	No · any member

Permissions and safety

Tools act as the signed-in user, on the workspace that user last opened in the web app (switch workspaces there to change it; verify_connection tells you which one is active). Viewers can read; owners and admins can write and manage keys. Tools that rotate or revoke keys, reset the sandbox, mint keys, or push customers (consent) are marked destructive so Claude asks before running them. The access token is verified by the MCP server and again by the API (signature, issuer, expiry, audience), and it can only reach the API console and OWL read routes, never billing, team or admin.

Claude Code skill

A telltale plugin with a guided /telltale:integrate workflow (backfill order, batch sizing, refund semantics, sandbox first) is prepared and will be published to a public marketplace. Until then, the MCP server above gives Claude Code everything the skill needs; ask it to start with get_docs. See also theAPI reference.

Without MCP

Any AI tool can still work from the machine-readable docs: https://api.telltale.pro/llms.txt, https://api.telltale.pro/llms-full.txt and https://api.telltale.pro/v1/openapi.json.