Connect Claude to Ballad

Ballad is an MCP server. Add it to Claude as a custom connector and Claude can read your workspace, draft posts and articles, propose plan changes, and check on runs — inside the same loop, with the same review gate you already use. This takes about five minutes.

1. Copy the connector URL

In Ballad, open Settings → Agents. The endpoint is shown at the top of the section with a Copy URL button. It looks like this:

https://app.balladlabs.com/api/mcp

2. Add a custom connector in Claude

In Claude, open Settings → Connectors and choose Add custom connector. Give it a name ("Ballad" works), paste the URL, and save. Claude will detect that the server supports sign-in.

3. Sign in with Ballad

Choose Sign in on the connector. Claude sends you to Ballad, where you sign in if you aren't already, and then to a consent screen:

• Who is asking — the app's name and domain.
• What it may do — one checkbox per scope, in plain language. read is always on. draft, propose and signals are on by default. decide and publish are off unless you tick them.
• Allow or Deny.

Narrow the scopes if you like; you can always reconnect later with more. Once you allow, Claude is connected and the app appears under Connected apps in Settings.

4. Try it

Ask Claude something that needs your workspace:

What's waiting for my review in Ballad?

Draft a LinkedIn post about the retry bug we fixed this week, in my voice.

Write a blog post on why shipping week is the best content week, and submit it to my blog collection with a hero image.

Every draft lands in your Inbox for review, exactly like Ballad's own. Every call shows in the Loop history with the connector as the actor.

What an agent can and can't do

The scopes are the whole permission model, and two rules never change:

• Drafts an agent makes always come to you for review. There is no scope that lets an agent skip the gate.
• An agent can approve only what you've already marked one-tap (with the decide scope), and nothing publishes without publish.

Scope	Lets the agent
read	See the workspace: drafts, lanes, plan, events, runs
draft	Start generation; submit or revise drafts (you still approve)
propose	Propose plan changes for you to approve
decide	Approve one-tap drafts, decline, undo, pin, set cadence
publish	Mark posts as posted; publish articles
signals	Record metrics for published pieces

Other agents: use a key

Clients that can't sign in (a script, an agent framework, Claude Code with a config file) use an agent key instead. In Settings → Agents, choose New agent key, name it, pick scopes, and copy the key — it's shown once. Then point the client at the same URL with the key as a bearer token:

{
  "mcpServers": {
    "ballad": {
      "type": "http",
      "url": "https://app.balladlabs.com/api/mcp",
      "headers": { "Authorization": "Bearer bak_…" }
    }
  }
}

The Copy client config button in Settings produces exactly this.

What you can ask for

Two tools do the making. generate hands Ballad a topic and lets it write; create_draft submits words you already have. Either way the result lands in your Inbox for review — the scopes above decide which tools an agent may call at all.

generate

generate({ kind, topic, personaId, collectionId, destination, launch })

topic is required; the rest are optional. collectionId picks the collection an article belongs to. destination is a page on your own site — for the two newsletter kinds it becomes the issue's call to action. launch carries { productUrl, whatsNew, subreddit } for the launch kinds.

kind	Makes
linkedin, x, bluesky, threads	A single post on that channel
thread, bluesky_thread, threads_thread	A multi-post thread on X, Bluesky or Threads
article	A long-form article for your blog
hn, reddit, producthunt	A launch piece — pass launch
linkedin_newsletter, email	A newsletter issue
linkedin_image, x_image, bluesky_image, threads_image, instagram_image	A single image card
linkedin_carousel, threads_carousel, instagram_carousel	A carousel

There's no x_carousel or bluesky_carousel: both channels cap a post at four images, so generate makes cards for them. That limit is generate's alone — a carousel of two to four slides submitted through create_draft is accepted on X and Bluesky, and publishes as a multi-image post. See Image posts & carousels for the caps and how they're enforced.

create_draft

create_draft({ format, channel, angle, personaId, destination, skipGate, ...fields })

channel is one of linkedin, x, bluesky, threads, instagram, hn, reddit, producthunt or email — omit it for articles. What else a call takes depends on the format:

format	Also takes
social	body
thread	posts — the posts in order
launch	fields
article	title, markdown, and optionally heroImage and collectionId
newsletter	fields — email takes subject, preheader, cta and body; LinkedIn takes title and body
visual	layout (card or carousel), slides of headline and optional sub, caption, and optionally backgroundPrompt or backgroundImage

skipGate keeps your words verbatim — it skips Ballad's voice edit, not the founder's review. Use it when the text is already the founder's own. Every agent draft still waits for approval, with no exception and no scope that changes that.

Everything else

Reading — describe_workspace (voices, channels, collections and where each one publishes, what's configured), list_items and get_item (drafts and posts), list_lanes (the weekly slots), preview_slots (what's scheduled next), list_events and get_run (loop history), get_attribution (which pieces brought traffic), list_conversations (the Hacker News threads worth joining).

Drafting and proposing — edit_draft revises a draft, suggest_topic puts an idea in the queue, propose_plan_change proposes a change to the plan for you to approve.

Deciding — decide approves or declines a one-tap draft, undo_decision takes it back, pin_item pins a piece to a time, decide_conversation acts on a conversation, set_cadence changes a lane's cadence, set_brand sets the workspace's colours, font, logo and handle (one look for every voice), and set_newsletter_tool sets which email tool you send from.

Publishing and signals — mark_published records that you posted something; on an article it publishes headlessly, or records it live where you put it if you pass the url. record_signal records how it did.

Disconnecting

Settings → Agents → Connected apps → Disconnect. Access ends immediately, including any tokens the app still holds; it can sign in again later. Keys are revoked from the same section.