# Ballet MCP endpoint

> Canonical: https://ballet.dev/mcp

Ballet exposes an inbound MCP server at https://api.ballet.dev/mcp over Streamable HTTP.
MCP-aware clients such as Claude, Cursor, Codex and Hermes connect there and get
Ballet's management surface as tools: list and run playbooks, read run results,
and build new workflows in your workspace.

Auth: OAuth 2.1 (auto-discovered) or a workspace API token.
Setup guide: https://ballet.dev/docs/developer/articles/how-do-i-connect-to-ballets-mcp-endpoint-1ydPKBzHZm

Generic client config:

```json
{
  "mcpServers": {
    "ballet": {
      "url": "https://api.ballet.dev/mcp"
    }
  }
}
```

Hermes (~/.hermes/config.yaml):

```yaml
mcp_servers:
  ballet:
    url: "https://api.ballet.dev/mcp"
    auth: oauth
```

## Authentication

### 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.

## Supported clients

### 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.

### 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).

## Example use cases

### 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. Playbook: https://ballet.dev/playbooks/lead-enrichment/

### 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. Playbook: https://ballet.dev/playbooks/weekly-reports/

### 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. Playbook: https://ballet.dev/playbooks/invoice-approvals/

### Ticket triage without leaving chat

Have an MCP client start your support triage playbook, then read back what was classified, drafted or escalated. Playbook: https://ballet.dev/playbooks/support-triage-draft-reply/

## FAQ

### 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.

## Where your team uses it

- [The Ballet platform](https://ballet.dev/product): Where a workflow gets written, reviewed, and watched once it's live.
- [Ballet Assist for Chrome](https://ballet.dev/chrome-extension): A side panel next to your CRM or helpdesk. Ask for something, or type / and pick a playbook.
- [Ballet for Claude](https://ballet.dev/claude): Connect Ballet in Claude and ask it to run a playbook, read what happened, or build a new one.
- [Ballet MCP](https://ballet.dev/mcp): Point any MCP client at api.ballet.dev/mcp. Authenticate with OAuth or a workspace API token.
- [Ballet for Slack](https://ballet.dev/slack): Mention Ballet on a message, or send it a DM. The result posts back in the thread.
