---
title: "How do I connect to Ballet's MCP endpoint?"
description: "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 runplaybook, getrun, and list_playbooks. Auth is OAuth 2.1 (auto-discovered) or a Bearer API token."
canonical_url: "https://docs.ballet.dev/articles/how-do-i-connect-to-ballets-mcp-endpoint-1ydPKBzHZm"
md_url: "https://docs.ballet.dev/articles/how-do-i-connect-to-ballets-mcp-endpoint-1ydPKBzHZm.md"
---
# 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:

```json
{
  "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](/articles/how-do-i-authenticate-with-the-ballet-api-tWaqCPLyGT).

## How does it work?

* The endpoint speaks MCP JSON-RPC over Streamable HTTP at `POST /mcp` (with `GET /mcp` for SSE sessions and `DELETE /mcp` to 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.

## When should I use MCP vs REST?

## Related articles

* [How do I connect an MCP server?](/articles/how-do-i-connect-an-mcp-server-RtBQhNBIoy)
* [How do I authenticate with the Ballet API?](/articles/how-do-i-authenticate-with-the-ballet-api-tWaqCPLyGT)
* [Run playbooks over the REST API](/articles/how-do-i-run-a-playbook-over-the-rest-api-KQIz0apagm)
* [Agent frameworks](/articles/how-do-i-use-ballet-playbooks-in-an-agent-framework-q3PWTx18lY)