How do I connect to Ballet's MCP endpoint?
TL;DR: Ballet exposes an inbound MCP server at https://api.ballet.dev/mcp over Streamable HTTP. MCP-aware clients (Cursor, Claude Desktop, and agent frameworks) connect there and get Ballet's management surface as tools — including run_playbook, get_run, and list_playbooks. Auth is OAuth 2.1 (auto-discovered) or a workspace API token.
Who this is for
Developers who want to expose Ballet to any MCP client or agent framework instead of hand-rolling REST calls.
How do I connect?
Point an MCP client at the endpoint. Clients that support OAuth discover the flow automatically from /.well-known/oauth-protected-resource and open a browser-based login:
{
"mcpServers": {
"ballet": {
"url": "https://api.ballet.dev/mcp"
}
}
}
The endpoint lives on api.ballet.dev, not app.ballet.dev. app.ballet.dev serves Ballet Studio and does not answer MCP requests.
How do I authenticate?
Two options:
- OAuth 2.1 — best for interactive clients. On first connection your client registers itself, you approve access in the browser, and Ballet issues a short-lived access token plus a refresh token. Nothing is copied by hand.
- Workspace API token — send
Authorization: Bearer mt_live_…. Use this 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. See authentication.
How does it work?
- The endpoint speaks MCP JSON-RPC over Streamable HTTP at
POST /mcp(withGET /mcpfor SSE sessions andDELETE /mcpto end a session). - The transport runs statelessly with JSON responses — each request creates a fresh server/transport pair.
- Your workspace and member identity are derived from the token, so tools act within your workspace.
What tools does it expose?
The endpoint exposes Ballet's management API as MCP tools. The ones most relevant to running automations:
list_playbooks— find a playbook and its ID.run_playbook— trigger a run and get back a run ID.get_run— poll status and results for a run.get_run_steps— read per-step results when diagnosing a failure.list_runs— recent run history, optionally filtered by playbook.
The ones most relevant to building:
list_builder_guidesandget_builder_guide— Ballet's own authoring guides. Call these before creating anything.list_integrations,list_models,list_secrets— discover what your workspace already has, so you do not rebuild it.verify_playbook— static wiring audit. Run it beforerun_playbook.
Additional tools cover full CRUD for playbooks, agents, skills, custom tools, connected MCP servers, and persistent data tables — so an MCP client can manage a workspace end to end, not just run playbooks.
When should I use MCP vs REST?
Use MCP when the caller is an agent or an LLM-driven client. The tools describe themselves, so the model discovers what is available instead of you maintaining a hand-written API layer.
Use the REST API when the caller is deterministic code that only needs to start a playbook and read its result — it is a single request with no tool-discovery round trip.
Both surfaces act on the same workspace and accept the same workspace API token, so you can build a playbook over MCP and run it from CI over REST.