MCP server for interacting with the Beehiiv API to manage publications and posts
Server has 5 tools with basic verb-noun naming (list_, get_, create_). All tools have descriptions (10-100 chars), but most are minimal and lack actionable context. Input schemas are present for all tools with type declarations, but parameter descriptions are sparse or missing. Output schemas are undocumented, tools return strings or dicts without specifying structure. Error handling is minimal (generic 'Failed to fetch' messages). No pagination, no field-level guidance, no recovery hints. The create_new_post tool is untested and returns a dict instead of a string, creating inconsistency. Overall: functional but well below production baseline (194 char avg description, 100% param descriptions in A+ tools).
Create a new post using provided HTML content.
Retrieve a single post by ID.
Retrieve a post's content as JSON to use as a template.
List all posts for a given publication.
List all publications accessible with this API key.
Output schemas undocumented. Tools return strings or dicts without specifying field names, types, or structure. LLMs cannot plan downstream calls or extract data reliably.
Parameter descriptions missing or minimal. 'publication_id' described as 'ID of the publication' (generic); 'post_id' similarly vague. No format hints, constraints, or examples of valid values.
Tool descriptions too brief (40-55 chars). Lack context on WHEN to use, WHAT it returns, and dependencies. E.g., 'List all posts for a given publication' omits that results are limited to 5 recent confirmed posts.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | F | 48 | 2026-07-28+ | v2 |
Error handling returns generic strings ('Failed to fetch the post') with no recovery guidance. LLMs cannot determine if error is retryable, user-fixable, or fatal.
create_new_post returns dict instead of string, breaking consistency with other tools. Also marked untested ('have not tested this as I am not an enterprise customer'), indicating incomplete implementation.