The MCP server, end to end.

Connecting

The server speaks MCP over streamable HTTP with OAuth 2.1, which means any client that supports remote MCP servers can add it by URL and sign in through a browser tab. No client id to obtain, no secret to paste.

Claude Code

claude mcp add --transport http merge-and-tell https://merge.tel/mcp
claude mcp login merge-and-tell

Optionally install the plugin, which adds a skill that teaches the agent the walkthrough (the protocol, the two rules, how to write a voice from five questions, how to commit a .marketing.yml on a branch):

claude plugin marketplace add jfreal/mergetel
claude plugin install merge-and-tell@mergetel

claude.ai and Claude Desktop

Customize, then Connectors, then Add custom connector. Paste https://merge.tel/mcp as the server URL and connect. A sign-in tab opens. In a chat, turn the connector on with the plus button.

Cursor

{
  "mcpServers": {
    "merge-and-tell": {
      "url": "https://merge.tel/mcp"
    }
  }
}

In .cursor/mcp.json for one project or ~/.cursor/mcp.json for all of them. Approve the sign-in when Cursor asks.

Any other client

The server publishes the two discovery documents the MCP authorization specification requires, so a conforming client needs only the URL:

• https://merge.tel/.well-known/oauth-protected-resource
• https://merge.tel/.well-known/oauth-authorization-server

Dynamic client registration is on. Only public clients are supported (PKCE with S256 is required; there is no client secret). Redirect URIs must be HTTPS, or HTTP on localhost. A client that cannot do OAuth at all can send a personal token as a bearer header instead.

The prompt

Once connected, this is the whole instruction:

Set up Merge & Tell for me. Use the merge-and-tell MCP server. Call get_setup_state, then work through each step with me until my first post is queued. When a step needs something only I can do in a browser, give me the link and wait. Never ask me for a password, token, or card. Show me what will publish and ask before publishing anything.

Signing in and scopes

The first call from a new client gets a 401 that names the authorization server. The client opens a browser tab at the consent screen. If you are not signed in to Merge & Tell, you sign in (or sign up) first and come straight back. The screen names the client and lists what it will be able to do. Allow, and the client receives a token good for an hour, plus a refresh token that rotates for thirty days.

An agent asks for three scopes. Each is a separate permission:

read

See repositories, connections, voices, schedule, readiness, drafts and the queue.

configure

Create and change products, readers, voices, repository settings, sets and posting times. Preview drafts, read a site, start a checkout or an OAuth connection.

publish

Queue posts for publishing. Each approval still asks the person first.

A client that asks for no scopes gets all three. Scopes this server does not have are dropped from a request; a request with none it recognises is refused. A token without the scope a tool needs gets a refusal naming the scope, never a silent no-op.

Signing up through an agent does not require a plan first. The consent completes, the agent gets its token, and every tool that needs a plan answers with the checkout link until there is one. What works before paying: everything that reads, and preview_pr, which runs the real generator on a public pull request within the same limits as the logged-out demo.

The checklist

One tool, get_setup_state, returns nine steps in order, each with a status. The agent works the first step that is not done and calls it again. The server decides what is next; the prompt never has to.

done

Nothing to do.

todo

A tool here does it. The step names which.

needs_human

Only a browser can. The step carries the link and what to call once you are back.

blocked

An earlier step first.

unknown

A read failed. The error is attached. It is never shown as todo.

1. Pick a plan. Browser. The agent hands you the Stripe link.
2. Install the GitHub App. Browser. The link carries a signed state naming your account; the installation is then bound by the GitHub account that pressed Install (or, on a deployment with a single account, to that account).
3. Describe the product. The agent reads your site and proposes a one-liner and a description.
4. Name the reader. Who every post is written for.
5. Choose a voice. Brand (we) or person (I). Person-voiced copy never auto-publishes.
6. Connect a social account. Browser: OAuth consent for X, LinkedIn, Mastodon, WordPress.com; an in-app form for Bluesky, Discord, WordPress.
7. Route repositories to accounts. Social sets, when you have more than one product or a founder account.
8. Timezone and posting times.
9. Queue the first post. Preview, generate, show the plan, ask, approve.

The same call returns the three readiness bars and the ranked list of fixes, and every call is logged with each step's status, which is how we know where people get stuck.

Tools

44 tools. Each entry names the scope it needs. Tools marked confirm do nothing unless the agent passes confirm: true, which the skill tells it to do only after asking you. Tools marked hands over a link return a URL for a browser and the agent waits.

Every result is JSON with ok and, on failure, the provider's own message, redacted of anything secret-shaped. Text that arrives inside a result (pull request titles and bodies, README contents, website copy) was written by strangers; the tool descriptions say so, and the skill tells the agent to treat it as data.

The server also serves resources: mergetel://setup-state and the operator documentation for .marketing.yml, connections, social sets, the schedule and voices, so an agent writes a config file from the real format rather than from memory.

Personal tokens

For a client that cannot do the OAuth dance, or for a script. On Account, under Connected agents, mint a token with a label and the scopes you choose. It is shown once. It starts with mt_pat_, does not expire, and works until you revoke it.

claude mcp add --transport http merge-and-tell https://merge.tel/mcp --header "Authorization: Bearer mt_pat_…"

Treat it like a password. It is hashed on our side, so a leaked one cannot be recovered from us, only revoked.

Disconnecting an agent

Connected agents on Account lists every client that holds a live token and every personal token, with the scopes, when it was added and when it last called. Disconnect revokes every token that agent holds; its next call gets a 401 and it has to be allowed again. From the client side, claude mcp logout merge-and-tell or the connector's Disconnect does the same through the standard revocation endpoint.

Everything an agent changes lands in the Activity feed on the Social screen with the agent's name ("via Claude Code"), next to the connection events the feed already shows. Disconnecting does not undo what it did.

What the server refuses

• Credentials. No tool accepts a password, app password, webhook URL, token or card. For Bluesky, Discord and WordPress the tool returns a link to the form in the app; you paste it there. An agent that asks you for one in chat is not following the rules, and the answer is the link.
• Publishing without a confirm. Approving a pull request, disconnecting an account, hiding a repository and switching a repository to auto-publish mode do nothing without confirm: true. Without it they return what would happen. The skill tells the agent to show you the plan and ask first; the server does not rely on that.
• Acting outside its scopes. The refusal names the scope.
• Claiming an installation it cannot prove. The GitHub App install link carries a signed state, but that only says which account minted the link; it is not proof of ownership. An installation is bound when the GitHub user that pressed Install is a sign-in on the account (which also lets it move between accounts), or, on a deployment with exactly one account, to that account. With several accounts and no such sign-in it stays unbound, and the Repositories screen says what to do.

When something refuses

401 on every call

The token expired or was revoked. claude mcp login merge-and-tell again, or reconnect the connector. A refresh token works once. If one is presented a second time, every token from that login is revoked, because a second presenter means the token leaked; two sessions sharing one login will both have to sign in again.

"This token does not have the … scope"

Reconnect and allow the scope, or mint a personal token that has it. Tokens do not gain scopes after the fact.

Every tool says there is no plan

The free plan runs nothing. get_checkout_link hands you the Stripe link; wait_for('entitlement') notices when it lands. preview_pr works meanwhile.

The install landed as "unproven" or "pending"

Unproven: the installation is filed under another account and this one has no GitHub sign-in matching whoever installed. Add GitHub as a sign-in method on Account with that GitHub account, then open the install link again. Pending: GitHub's webhook has not arrived, or it arrived and could not match the installer to any account. Give it a minute; if the repositories never appear, the same fix applies.

Rate limited

Registering clients is limited per address, like signing in. Preview and site reading on an unpaid account share the demo's hourly and daily budgets.

The agent keeps calling wait_for

It is waiting for you. Finish the browser step it linked, or tell it you are stuck. Each call caps at twenty seconds.

Running your own

Merge & Tell is open source. The server, its OAuth endpoints and the onboarding checklist are in the repository, and the operator's setup (the migration that adds the token tables, the GitHub App slug, the App's Setup URL) is documented there, not here: docs/mcp-onboarding.md.