Model Context Protocol

Run Ballet from Claude, Cursor, Codex and Hermes

Ballet exposes an inbound MCP server at api.ballet.dev/mcp over Streamable HTTP. Point a supported client at it, sign in with OAuth or a workspace API token, and the client can list playbooks, run them, read results and build new workflows in your workspace.

Running ops automations at

  • Mixpanel
  • HireVue
  • Pave
  • Buffer
  • SnapLogic
  • Huntress

Streamable HTTP, with OAuth or a token

The endpoint speaks MCP JSON-RPC over Streamable HTTP. Interactive clients discover OAuth automatically; programmatic clients send a workspace API token.

OAuth 2.1

Best for interactive clients. The client discovers the flow from /.well-known/oauth-protected-resource, you approve access in the browser, and Ballet issues a short-lived access token plus a refresh token.

Workspace API token

Send Authorization: Bearer mt_live_… for programmatic clients that cannot open a browser, such as CI jobs, backend services and agent frameworks. The token acts with the role it was minted for.

Client config
{
  "mcpServers": {
    "ballet": {
      "url": "https://api.ballet.dev/mcp"
    }
  }
}

Set up the clients your team already uses

Same endpoint and same workspace. Pick the client your team works in.

Claude

Add Ballet from Claude's connector directory, or point Claude Desktop at the MCP endpoint. Claude can search playbooks, run one, read what happened, and build new workflows.

Claude connector page

Cursor

Add a remote MCP server in Cursor settings with url https://api.ballet.dev/mcp. Complete OAuth when prompted, or supply a workspace API token for headless use.

Codex

Configure the Ballet MCP server the same way as other remote MCP servers in Codex: url https://api.ballet.dev/mcp, then authenticate with OAuth or a workspace API token.

Hermes

In ~/.hermes/config.yaml, add mcp_servers.ballet with url https://api.ballet.dev/mcp and auth: oauth (or a token when OAuth is not available).

Hermes, in ~/.hermes/config.yaml
mcp_servers:
  ballet:
    url: "https://api.ballet.dev/mcp"
    auth: oauth

What teams ask MCP clients to do

The playbook is the same whether you start it from Studio or from a conversation.

Lead enrichment from Claude

Ask Claude to enrich a new lead against your CRM and enrichment tools, then write the result back through a reviewed Ballet playbook.

See the playbook

Weekly reports on a schedule

Describe the report once. Ballet builds it as reviewable code, runs it on a schedule, and can be re-run from Cursor or Claude when someone asks for an update.

See the playbook

Invoice approvals with a human gate

Route invoice or expense approvals across finance systems, pause for a person when the amount needs judgment, and keep every step on record.

See the playbook

Ticket triage without leaving chat

Have an MCP client start your support triage playbook, then read back what was classified, drafted or escalated.

See the playbook

Frequently asked questions

Where is the Ballet MCP endpoint?

https://api.ballet.dev/mcp on Streamable HTTP. It lives on api.ballet.dev, not app.ballet.dev. Studio at app.ballet.dev does not answer MCP requests.

How do I authenticate?

Use OAuth 2.1 for interactive clients (auto-discovered), or a workspace API token with Authorization: Bearer mt_live_… for programmatic clients.

Which clients are supported?

Any MCP-aware client that can reach a remote Streamable HTTP server. Documented setups cover Claude, Cursor, Codex and Hermes.

What can a client do once connected?

List and run playbooks, read run status and steps, manage agents, skills, tools, secrets, data tables and integrations, and follow Ballet's builder guides before creating new work.

Is there a longer setup guide?

Yes. See the help article at https://ballet.dev/docs/developer/articles/how-do-i-connect-to-ballets-mcp-endpoint-1ydPKBzHZm.

Full setup detail: How do I connect to Ballet's MCP endpoint?

Connect your MCP client

Point it at https://api.ballet.dev/mcp, sign in, and the next message can run a playbook.