You’re reading Release Notes, a weekly newsletter covering product lessons from scaling beehiiv and building AI products in the creator economy. (Read the full archive here.)
If you're new here, I'm Jake, a product expert in the creator economy, currently a Senior Product Manager at beehiiv.
Sponsored by
Intro
Last week, we launched the beehiiv MCP - over 10% of our users requested access in the first 24 hours.
It’s on track to be our most rapidly adopted feature to date.
Why? The MCP allows our users to dive into their beehiiv data like never before - unlocking things like analyzing subject line performance, the impact of content type on click through rate and much much more. eg.
Claude analysis completed with beehiiv MCP
This newsletter covers everything I learned during the build & design process, so you can build your own.
Here's what we cover:
What an MCP actually is (and what it isn't)
Why we built an MCP
How an MCP is actually built
How the beehiiv MCP works under the hood
How to design your MCP tools
The segments challenge: handling complex queries
The write access roadmap
Let's get into it.
1. What is an MCP?
MCP stands for Model Context Protocol — an open standard introduced by Anthropic that lets AI tools like Claude or ChatGPT connect directly to external products and services.
Here's the simple version:
An MCP allows an AI agent to interact with a tool on your behalf. eg. Instead of exporting a csv/document from a tool and uploading it into Claude/ChatGPT, the MCP allows your agent to just go and get the data itself from the tool.
What’s the difference between an API and MCP?
The analogy I use internally:
The API is a machine talking to another machine, ie. deterministic, structured, versioned. You request/send information and you get a consistent response from the other app.
The MCP is for an AI agent talking to your product. It's looser, richer, and designed for a different type of interaction entirely.
[sponsored]
Replace your first 4 hires with AI. Free workshop on April 8th.
Most early-stage founders can't afford their first four hires. Sales, marketing, dev, and support alone can run hundreds of thousands in salaries.
On April 8th, AI thought leader Heather Murray shows pre-seed and seed founders how to build all four functions using AI tools. Live, with demos, for free.
Register today and get a free AI tech stack worth $5K+ including Claude, AWS credits, Make, and 90% off HubSpot.
2. Why we built an MCP
Three reasons:
Context: our users are already running AI workflows, and those workflows are only as useful as the context they have access to. Your newsletter data, your subscriber analytics, your post history - all of it is currently locked inside beehiiv, invisible to whatever AI tool you've set up. The MCP fixes that and allows you to introduce beehiiv into your workflow.
The future of UX: User → Agent → Product interactions are quickly becoming one of the primary methods for interacting with products. In the same way you invest lots of time/resources in optimizing Mobile & desktop experiences, the reality is that today products also need to optimize the agent experience.
The less obvious one: in order to provide a magical, AI-assisted in-product experience, you need to have the right infrastructure in place. The rails that support the MCP will unlock a whole new UX paradigm which we can utilize in the future.
The best example of this is Linear (one of my favorite products), who spent months iterating their MCP tools externally via slack agents before rolling out the same capabilities as a first-class in-product experience. This work unlocks that future for us too.
3. How an MCP is actually built
An MCP server is, at its core, a collection of tools. Tools are just pre-defined functions within your product that an AI agent can call when it decides they're relevant.
Each tool has four components:
A name — what the agent calls it (e.g.
list_posts,get_publication_stats)A description — plain English that tells the agent what the tool does and when to use it. This is more important than it sounds. The agent's decision about which tool to call is driven almost entirely by how well the description is written.
An input schema — the parameters the tool accepts, defined in JSON Schema
A handler — the server-side function that actually runs when the tool is called
The agent sends a request, the MCP server runs the tool, and the result comes back as structured text that the agent uses as context.
Authentication is what decides whether the agent can interact with the tools (and which data they can access). When a user connects beehiiv in Claude or ChatGPT, they get redirected to a beehiiv authorisation page, approve access, and the AI tool stores the token. Every subsequent tool call is authenticated against that token when it reaches the mcp server.
One thing to understand: the agent decides which tools to call.
You don't instruct it. You write tool descriptions clearly enough that the agent figures out the right sequence on its own. This is one of the key differences from building a traditional API integration - you're not writing code that calls your own endpoints, you're writing descriptions that train the AI to call them correctly.
4. How the beehiiv MCP works under the hood
The beehiiv MCP server lives at mcp.beehiiv.com/mcp. It sits behind Cloudflare, which handles rate limiting and security rules.
In the current v1, we expose the following tools:
get_workspace— returns workspace-level metadata. The MCP is workspace-scoped, not publication-scoped.list_publications— lists all publications in the workspaceget_publication— returns detail on a specific publicationget_publication_stats— returns subscriber counts, growth metrics, and engagement rateslist_posts— paginated list of posts with status, dates, and headline metricsget_post— detail on a specific postget_post_content— full post content (used for tone of voice analysis, grammar checks, generating social content)get_post_stats— open rates, click rates, and delivery data for a specific sendlist_subscriptions— paginated list of subscribers with status and engagement dataget_subscription— detail on a specific subscriber
All read-only. All returning richer, more contextual payloads than you'd get from the API, because the consumer is an AI that benefits from prose context, not just raw JSON.
5. How to design your MCP tools
When you’re designing your MCP, you need to have an implementation plan for your tools.
Do you map your tools to the existing product & endpoints (General purpose tools) vs creating Intent-based tools (compound tools).
General-purpose tools
The agent calls simple tools eg. list_posts, get_post_stats, list_subscriptions, and handles the logic itself. More flexible. Easier to build. Every new combination doesn't require a new tool.
The downside: users rarely ask basic questions, so you're relying on the agent to correctly chain multiple calls and reason about the result. That works well for simple queries. For complex multi-step workflows, you're asking a lot.
Intent-based tools (compound tools)
These are highly specified tools eg. getDomainSpecificDeliverabilityData
The agent makes one call, gets back exactly what it needs and doesn't have to figure out which of four separate calls to make, in what order, and how to stitch the results together.
The downside: For complex queries with five or more steps, the error surface gets large fast (higher chance agent misreads context). Also, this specialised approach typically leads to a lot of tools. Each one needs to be built, maintained, and described.
In reality, most MCP clients limit you to somewhere between 20 and 128 tools depending on the model. Blow past it and the agent's tool selection becomes unreliable - it starts calling the wrong thing because it can't hold the full list in context cleanly.
6. Which MCP tools to include in your MVP
We made two key decisions for the scope of V1.0 of our MCP:
Start with read-only tools (You can ask for data via an agent but not make any changes)
Start with general-purpose tools
The logic: we don't yet have real usage data yet and AI workflows are rapidly evolving so there’s no way to reliably predict what they need.
We also don't know which queries users will run most, which flows need five chained calls, or where the agent will struggle. Building a library of intent-based compound tools before we have that data would be guessing.
So V1 serves to collect the data and understand the user behavior.
The plan for v2 onwards is to analyze the data, and then selectively add intent-based tools. These will be based on our most frequently used tool-chains and workflows.
This allows us to make sure our MCP roadmap aligns exactly to what our users need.
7. The segments challenge: handling complex queries
One of the most interesting product problems we hit was around complex subscriber queries with ranking.
eg. "Who are my 100 most engaged free subscribers who haven't converted to paid in the last 90 days?"
The general tools we launched in V1.0 let an agent list subscribers and fetch detail on individual ones. That works well for simple lookups. It breaks down for more complex, ranked queries like above.
That's not a list operation. That's a segment (a powerful feature in beehiiv for managing and segmenting different users based on behaviour/attributes)
One option was to allow complex queries to generate a segment within a user’s beehiiv account. However, this has obvious downsides with accounts quickly getting polluted with these query-segments.
We then introduced the idea of a temporary segment, that could be created in response to a query, but would be deleted after the results are returned. This preventing any account clutter.
The solution we are now working towards: User requests information via agent → list existing segments to see if any cover it already → create a segment if needed → list subscribers from the segment → remove new segment.
The key is working with your product to unlock the core use-cases for your users.
I hope you found this useful. If you have any questions/feedback, just hit reply.
If you're on a paid plan, you can request MCP access at beehiiv.com/features/mcp. If you build something interesting with it, I want to hear about it.
If you know a PM, founder, or creator economy operator who'd find this useful, please send them the link.
Cheers,
Jake
PS. If you’re considering launching your own newsletter, you can get a free month & 20% off by clicking here.
