How do I connect external MCP servers to playbooks?
TL;DR: Ballet acts as an MCP client to external servers. Add a server from the registry or a custom URL under Connectors, authenticate with OAuth or an API key, and its tools become available to steps and agents. OAuth uses discovery + PKCE so most servers connect without pasting tokens.
Who this is for
Developers giving playbooks access to external services that expose an MCP server.
How do I connect a featured server?
- Open Connectors → Browse registry.
- Pick the service (GitHub, Slack, Linear, Brainfish, Stripe, …) and click Connect.
- Authenticate — OAuth sign-in, or paste an API key in the Authorization header.
- Confirm the connection shows as active.
When a connect attempt fails because a token is missing, Ballet probes the server's OAuth discovery endpoints and opens the authorization popup automatically if the server supports it.
How do I connect a custom MCP server?
- Go to Connectors → Add connector.
- Enter the MCP server URL (HTTP or SSE endpoint).
- Add required headers (for example
Authorization: Bearer ${MY_TOKEN}), referencing Secrets with${VAR}. - Save and test the connection.
What auth methods are supported?
| Method | Example services |
|---|---|
| OAuth (discovery + PKCE) | Slack, Linear, Notion, GitHub |
| API key | Brainfish, Stripe, Supabase, Datadog |
| Custom headers | Provider-specific (for example a client ID + secret) |
OAuth tokens are stored in Ballet's per-tenant encrypted secret store and refreshed automatically near expiry.
How do playbooks use connected tools?
Reference the connected server's tools from Code steps, or let Ask Ballet wire them while building. A playbook can also attach connectors in its own Connectors panel for playbook-specific access.