---
title: "How do I connect external MCP servers to playbooks?"
description: "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."
canonical_url: "https://docs.ballet.dev/articles/how-do-i-connect-external-mcp-servers-to-playbooks-5Nd68jcOxW"
md_url: "https://docs.ballet.dev/articles/how-do-i-connect-external-mcp-servers-to-playbooks-5Nd68jcOxW.md"
---
# 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?

1. Open **Connectors** → **Browse registry**.
2. Pick the service (GitHub, Slack, Linear, Brainfish, Stripe, …) and click **Connect**.
3. Authenticate — OAuth sign-in, or paste an API key in the Authorization header.
4. 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?

1. Go to **Connectors** → **Add connector**.
2. Enter the MCP server URL (HTTP or SSE endpoint).
3. Add required headers (for example `Authorization: Bearer ${MY_TOKEN}`), referencing Secrets with `${VAR}`.
4. 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.

## Related articles

- [How do I connect an MCP server?](/articles/how-do-i-connect-an-mcp-server-RtBQhNBIoy)
- [What is a connector and how do I browse the registry?](/articles/what-is-a-connector-and-how-do-i-browse-the-registry-6PxIdsLTWe)
- [How do I store credentials with Secrets?](/articles/how-do-i-store-credentials-with-secrets-1D8OUcCo0n)
- [HTTP and custom tools](/articles/how-do-i-call-external-apis-and-sdks-from-a-playbook-zX7zFTnqwC)