How to Connect the beehiiv MCP Server to an AI Agent (2026 Guide)
The beehiiv MCP server lets an AI agent operate your newsletter directly — drafting posts, sending campaigns, managing subscribers, and pulling analytics across roughly 129 tools. We connected it for real this week, and the official setup notes leave out a few things that will trip you up. This is the honest, step-by-step version, including the gotchas nobody warns you about.
What Is the beehiiv MCP Server?
MCP — the Model Context Protocol — is an open standard that lets AI agents talk to external tools and services through a consistent interface. Instead of writing custom glue code for every API, you point your agent at an MCP server and it gets a structured catalog of actions it can take. The beehiiv MCP server is beehiiv's hosted implementation of that standard, exposing your newsletter platform as a set of agent-callable tools.
In practice, that means an AI agent connected to the beehiiv MCP server can do most of what you'd do in the dashboard: create and edit posts, schedule and send campaigns, add and segment subscribers, read engagement analytics like open and click rates, and work with automations and subscription tiers. The catalog we connected to had around 129 tools — broad enough that the agent can run real operational work, not just fetch a stat or two.
Why does this matter in 2026? Because it collapses the gap between "analyze my newsletter" and "act on it." You can ask an agent to look at last week's performance, draft the next issue in your voice, segment the send to your most engaged readers, and queue it — all in one conversation. The setup, though, has a few sharp edges. Here's how to get connected cleanly.
Step-by-Step: Connecting the beehiiv MCP Server
Open your MCP client's connector settings
In an MCP-capable client like Claude Desktop, go to Settings → Connectors → Add custom connector. Any client that supports remote MCP servers over HTTP works the same way — you're registering a remote endpoint, not installing a local package or running anything in a terminal. There is nothing to npm-install and no local process to keep alive.
Add the remote connector URL
Paste the beehiiv MCP server URL: https://mcp.beehiiv.com/mcp. This is the hosted, remote MCP endpoint — beehiiv runs it for you. Give the connector a recognizable name (e.g. "beehiiv") and save. At this point the connector exists but is not yet authorized, so no tools will be callable until you complete the sign-in step.
Authorize via OAuth in your browser
When you connect, the client opens a browser window and sends you to beehiiv's OAuth consent screen. Sign in with your normal beehiiv account credentials and approve the access request. This is the part the official docs get misleading about — you do NOT paste an API key. Authentication is interactive OAuth, granted to your logged-in beehiiv session.
Survive the localhost redirect error
After you approve, the browser redirects to a localhost callback URL (something like http://localhost:PORT/callback?code=...). In many setups that page renders a browser "can't connect / this site can't be reached" error. This is expected, not a failure. The authorization code your client needs is right there in the URL of that error page. Your MCP client is listening on that local port and captures the code automatically; if it doesn't, copy the code from the address bar back into the client when prompted.
Confirm the tools loaded
Once the handshake completes, the connector flips to connected and the beehiiv tool catalog loads. Ask your agent to list its available beehiiv tools or simply request something read-only first — "show my publications" or "pull this week's open rate" — to confirm the grant works before you let it write anything.
The connector URL, for reference
https://mcp.beehiiv.com/mcpAdd this as a custom remote connector in your MCP client. No local install, no API key field — authentication happens through the browser OAuth flow described above.
5 Gotchas the Docs Don't Warn You About
It's OAuth, not an API key
The single biggest point of confusion. Documentation framing implies you authenticate the beehiiv MCP server with an API key, but in practice the connector uses an interactive browser OAuth flow tied to your beehiiv login. If you go hunting for an API key field in your MCP client, you'll waste time — there isn't one. Just connect and approve in the browser.
The localhost "can't connect" page is normal
The OAuth redirect lands on a localhost callback that frequently shows a connection-error page. New users assume the setup broke and start over. Don't. The authorization code is embedded in that page's URL and your client reads it from the local listener. Treat the error page as the success page.
You likely get write access, despite read-only docs
Some documentation suggests the current version is read-only. In our setup, the OAuth grant came back with read AND write scope — create posts, send campaigns, and manage subscribers were all live immediately. That's powerful, so treat the connection with the same caution you'd give any credential that can email your entire list. Start the agent on read-only tasks and review what it proposes before approving sends.
You can't rename a publication through MCP
There is no MCP tool (and no public API endpoint) to rename a publication. That action is dashboard-only. If you ask your agent to rename a newsletter, it can't — you'll need to do it manually in the beehiiv web app under publication settings. Knowing this up front saves a frustrating round of "why won't it do this."
Bulk subscriber import goes through the REST API, not one MCP tool
Adding subscribers one at a time is fine via MCP, but importing a list of thousands is not a single MCP call. Bulk import is handled through beehiiv's REST API (the bulk subscription endpoint). For a large migration, script against the REST API directly; use the MCP server for the ongoing operational work — drafting issues, segmenting, and reading analytics.
What to Do Once You're Connected
Start read-only. Ask your agent to list your publications, summarize the last few issues' performance, or identify which segment of subscribers is trending toward churn. These calls are safe, they confirm the grant works, and they immediately surface whether the analytics tools return what you expect.
Then graduate to drafting. Have the agent write the next issue using your past posts as a style reference, then review it in the beehiiv editor before anything goes out. Because the connection can have write and send scope, build a habit of human approval on the final send step — never let an agent fire a campaign to your whole list unattended. The convenience is enormous, but so is the blast radius if a draft goes out half-finished.
For the operations MCP can't do — renaming a publication, bulk-importing thousands of subscribers — drop down a level. Renames happen in the dashboard; large imports run through beehiiv's REST API bulk endpoint. Use the MCP server for the recurring creative and analytical work where an agent actually saves you time, and reserve the manual paths for the one-off account-level tasks.
Frequently Asked Questions
Is the beehiiv MCP server free?
The MCP server itself is provided by beehiiv at no separate charge — there is no add-on fee to connect it. What you can do through it is governed by your existing beehiiv plan and account permissions. In other words, connecting costs nothing, but the underlying features (paid subscriptions, automations, custom domains, and so on) still depend on whatever plan tier you're on. If a tool call fails with a permissions or plan error, the limitation is your beehiiv plan, not the MCP layer.
Does the beehiiv MCP server support write access?
Yes, in our experience it does. Despite documentation that implies read-only access, the OAuth grant returned read and write scope, which meant the connected agent could create and edit posts, send campaigns, and manage subscribers. Because that's a high-trust level of access, treat the connection carefully: keep an eye on what your agent proposes, require human review before any send, and revoke the connector's access in your beehiiv account settings if you ever want to lock it back down.
Why does the OAuth redirect show an error page?
Because the OAuth flow redirects to a localhost callback URL, and your browser often can't render anything meaningful at that local address — so it shows a generic 'can't connect' or 'this site can't be reached' page. This is expected behavior, not a broken setup. The authorization code your MCP client needs is contained in that page's URL. The client is listening on the local callback port and captures the code automatically; if it asks you to paste the code, copy it from the address bar of that error page.
Can the beehiiv MCP server rename a publication?
No. There is no MCP tool and no public API endpoint to rename a publication — renaming is a dashboard-only action. You'll need to log into the beehiiv web app and change the name in your publication settings manually. The MCP server is excellent for content operations (drafting, sending, segmenting, analytics) but a handful of account-level settings remain web-only.
How many tools does the beehiiv MCP server expose?
Roughly 129 tools in the catalog we connected to. They span the full newsletter workflow: creating and editing posts, scheduling and sending campaigns, managing subscribers and segments, pulling analytics like open and click rates, working with automations, and handling subscription tiers. That breadth is what makes the integration genuinely useful — your agent can run most day-to-day newsletter operations rather than just reading a couple of stats.
Which MCP clients can connect to it?
Any client that supports remote MCP servers over HTTP. Claude Desktop is the most common path — Settings → Connectors → Add custom connector → paste https://mcp.beehiiv.com/mcp — but the same remote URL works in other MCP-capable agents and IDE integrations that allow custom remote connectors. Because it's a hosted remote server, there's no local install step regardless of which client you use.
Going Deeper on beehiiv
Thinking about whether beehiiv is the right home for your newsletter in 2026? Read our full review and head-to-head comparison.
Affiliate disclosure: Some links on this page are affiliate links. If you sign up through them, AISO Tools may earn a commission at no extra cost to you. This never affects our rankings or reviews.
📬 Get the best new AI tools delivered weekly
One concise email with fresh launches, trending picks, and featured standouts.
Join thousands of professionals who discover the best AI tools every week. No spam — unsubscribe anytime.