How do I connect to Ballet's MCP endpoint?
TL;DR: Ballet exposes an inbound MCP server at https://app.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 Bearer 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://app.ballet.dev/mcp"
}
}
}
For programmatic clients, send a workspace API token as a Bearer credential (Authorization: Bearer mt_live_…) — the transport accepts MCP OAuth tokens or a Bearer token. 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:
Additional tools cover full CRUD for playbooks, agents, skills, custom tools, and connected MCP servers — so an MCP client can manage a workspace end to end, not just run playbooks.