XCut AI for developers

XCut AI has one public API: a remote Model Context Protocol (MCP) server. This page is the reference for calling it from your own agent or app — endpoints, authentication and scopes, a sandbox call that needs no account, the error model, rate limits, and how to read xcut.ai itself as an agent.

What the API is

XCut AI is built to be called by AI assistants, so its API is an MCP server rather than a bespoke REST surface: ChatGPT, Claude, Grok, Gemini, Cursor, VS Code, Codex and any client that speaks remote MCP can use it unchanged, and so can your own agent with an MCP client library or plain HTTP. The server exposes 39 tools (35 in the Claude build, which omits AI image generation) covering outlier research on Instagram, TikTok, YouTube and Facebook, Meta Ad Library search, transcription and breakdown of pasted videos, and writing scripts, hooks, captions, carousels and content plans with the user's saved brand memory.

There is no separate REST API and no SDK to install. Everything below is reachable with curl.

Quickstart: list the tools (no account)

The transport is Streamable HTTP in JSON mode: one JSON-RPC 2.0 request per POST, one JSON response, no session header. initialize is optional on this server; tools/list works directly.

curl -sS https://mcp.xcut.ai/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Each tool in the response carries its JSON Schema (inputSchema), a description that starts with when to use it and when not to, and a securitySchemes field: [{"type":"noauth"}] for the free tools, OAuth with the required scope for the others.

Sandbox: call a free tool

The free tools are the sandbox. They need no account, cost no credits and return real data, so you can wire up a client end to end before any sign-in: xcut_find_hooks, xcut_get_playbook, xcut_hook_ideas, xcut_write_caption, xcut_rewrite_bio, xcut_youtube_titles, xcut_analyze_script, xcut_audit_content, xcut_posting_plan, xcut_competitor_gaps, xcut_check_niche and xcut_repurpose_content.

curl -sS https://mcp.xcut.ai/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc": "2.0", "id": 2, "method": "tools/call",
    "params": {
      "name": "xcut_find_hooks",
      "arguments": {"topic": "productivity for freelancers", "limit": 3}
    }
  }'

A successful call returns result.structuredContent (typed JSON) and the same data as text in result.content. Anonymous calls share a per-IP budget of 20 calls with a refill of one call every five seconds, and a global allowance of 5,000 anonymous calls a day; past either you get a RATE_LIMITED tool error with retry_after_s, not a dropped connection.

Connect an existing AI app

If you are not writing code, the setup guide has click-by-click steps per app. The URLs are the same everywhere:

Authentication and scopes

Account tools are protected with OAuth 2.1. The server publishes RFC 9728 protected-resource metadata and RFC 8414 authorization-server metadata, so a conforming MCP client discovers everything from the first 401. Authorization code with PKCE (S256) only; public clients register dynamically at the registration endpoint or present a client ID metadata document; tokens are bearer tokens in the Authorization header. Request the smallest scope the job needs:

A call to a protected tool without a usable token answers 401 with the metadata URL and the scope it needs in WWW-Authenticate; a token that lacks the scope answers 403 insufficient_scope the same way. The challenge asks for every scope the tool set needs at once, because hosts do not reliably carry step-up scopes forward:

HTTP/1.1 401 Unauthorized
Content-Type: application/json
WWW-Authenticate: Bearer error="invalid_token", error_description="Sign in to XcutAI to use this tool.",
  resource_metadata="https://mcp.xcut.ai/.well-known/oauth-protected-resource/mcp",
  scope="xcut.read xcut.write"

{"error": "invalid_token", "error_description": "Sign in to XcutAI to use this tool."}

API keys

For clients that cannot run an OAuth flow (Meta Muse custom connectors, scripts, servers), create a personal API key in the XCut AI app under Settings → Connected apps. Keys start with xcut_sk_, carry the scopes you chose when creating them, and are sent exactly like a token: Authorization: Bearer xcut_sk_…. Revoking a key on the same page stops it within about a minute. Keys act as you, on your credits, so keep them out of client-side code.

Endpoints

Requests over 1 MB are refused with 413. Tool calls that need longer than about 25 seconds (bulk imports, agents) return a job_id; poll xcut_get_job with it. No single call runs past 50 seconds; past that you get TIMEOUT and the same inputs resume the work on retry.

Errors

Every failure is JSON. Which shape you get depends on the layer that failed:

Tool errors

A tool error is one object with a machine-readable code and a sentence written for the person in the chat. retryable says whether repeating the same call can help; retry_after_s is present when waiting is the fix.

{
  "error": "RATE_LIMITED",
  "message": "XcutAI is handling too many requests for this account right now. Wait a minute and try again.",
  "retryable": true,
  "retry_after_s": 60
}

HTTP problems

HTTP/1.1 404 Not Found
Content-Type: application/problem+json

{
  "type": "about:blank",
  "title": "Not Found",
  "status": 404,
  "detail": "No route at /v1/hooks. The MCP endpoint is POST /mcp; see https://xcut.ai/developers.",
  "instance": "/v1/hooks"
}

Reading xcut.ai as an agent

• Every HTML page on xcut.ai returns Markdown from the same URL for Accept: text/markdown (Content-Type: text/markdown; charset=utf-8, Vary: Accept). Unknown URLs return a Markdown 404 for that header and an RFC 9457 problem document for Accept: application/json.
• llms.txt is the short index with a "when to use XCut AI" section; llms-full.txt has the feature, model and pricing tables; pricing.md is the price list with per-action credit costs.
• sitemap.xml lists every indexable page; robots.txt and ai.txt state the crawl policy (public pages open, /api/ and /admin/ closed).

Frequently asked questions

Is there a REST API?

No. The MCP server is the API: one POST endpoint speaking JSON-RPC 2.0, callable from any language with an HTTP client. The OpenAPI document describes that endpoint, its security schemes and its error responses.

Do I need an account to try it?

No. The twelve free tools (hooks, playbooks, captions, bios, titles, script analysis, content audit, posting plans, competitor gaps, niche checks, repurposing) run without sign-in and cost nothing. Tools that read or change a workspace, import content or run agents need an XCut AI account and use its credits.

OAuth or API key — which should I use?

OAuth when a person is present to sign in (assistants, IDEs): the token is scoped, short-lived and refreshable. An API key when nothing can open a browser (servers, scripts, Meta Muse): it is created and revoked in Settings → Connected apps and sent as a bearer token.

Where do I report a problem with the API?

Email [email protected] with the request path, the time (UTC) and the instance or job_id from the error. Tool errors include a sentence meant for the person in the chat; it is safe to show as is.

References

• Model Context Protocol specification, 2025-06-18 — transport, JSON-RPC envelope, tools and resources
• RFC 9728, OAuth 2.0 Protected Resource Metadata and RFC 8414, Authorization Server Metadata
• RFC 9457, Problem Details for HTTP APIs — the application/problem+json error shape
• RFC 9727, api-catalog well-known URI — the catalog at /.well-known/api-catalog
• acceptmarkdown.com — Markdown content negotiation as implemented on xcut.ai