MCP endpoint

Tale is itself an MCP server. Point any MCP client — an agent harness, an IDE, your own SDK loop — at one endpoint and it can author and operate automations, search what the organization can do, invoke a capability, and retrieve knowledge, with the same API key the REST surface takes. Where REST is the connector seam for your code, the MCP endpoint is the seam for models: every tool answers text a model can read and act on.

Read this to connect a client and understand the tool inventory. The grammar for authoring automations is deliberately not duplicated here — the endpoint teaches it itself through get_docs.

Connect a client

The endpoint speaks MCP protocol 2025-03-26 as JSON-RPC over HTTPS — plain JSON responses, no SSE stream, one message per request (a batch answers error -32600). Authenticate with an organization API key (API keys covers minting one):

// POST https://your-host.example.com/api/v1/mcp
// Authorization: Bearer tale_...
{ "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {} }

The server identifies as tale-platform. In a client that takes a config block, that is all you need:

{
  "mcpServers": {
    "tale": {
      "url": "https://your-host.example.com/api/v1/mcp",
      "headers": { "Authorization": "Bearer tale_..." }
    }
  }
}

tools/list returns the full inventory; GET on the endpoint answers 405 — there is no event stream to subscribe to.

The tools

Twenty-two tools, in three groups. The authoring tools take whole automation documents and validate everything themselves — their schemas are open on the wire, and get_docs is the reference a model reads first. The management and capability tools take simple arguments and declare real JSON schemas.

Authoring

Run & trigger management

Pick run_deployed when the automation is quick and you want one call with the answer in it. Pick start_run when the run may take minutes — it returns a runId immediately, and get_run polls it. Both run live.

start_run also takes an optional projectId — the project the run operates in, so its task and document tools act there. Omit it for an organization-wide run, or, when the automation is bound to a single project, that one. A bound automation accepts only a project it is bound to.

Capabilities & knowledge

This is the same registry a chat turn sees: one namespace over builtins, connector actions, skills, automations, and connected MCP tools. A capability the organization gates behind approval does not silently run — invoke_capability answers a pending-approval result the model can relay.

What the key may do

The key proves who is calling; the key holder's role decides what the call may do, exactly as in the product:

• Any member key — every read tool, run_automation in mock mode, search_capabilities, get_knowledge.
• Developer capability required — save_automation, deploy_automation, set_trigger, delete_trigger, cancel_run, and live execution (run_deployed, start_run, run_automation in live mode).

A refused call is not a protocol error: the tool answers a readable refusal — {"error": "...", "hint": "..."} — so the calling model can adjust instead of crashing. That convention holds everywhere: validation problems, missing deployments, and role refusals all come back as data; isError is reserved for a call that actually threw.

Where this fits

The MCP endpoint and the REST API are one surface with two dialects — same key, same organization scoping, same run objects (start_run here and POST .../runs there produce the same durable run). Building an MCP server of your own that Tale consumes is the opposite direction — that is MCP servers under connectors.