Beehiiv Analytics MCP Server

Instructions

Implementation Reference

• beehiiv_mcp_server.py:459-465 (handler)

  MCP tool handler in the call_tool function that handles the get_segment_details tool invocation by parsing arguments, calling the API client method, and returning the result as MCP content.

  elif name == "get_segment_details":
      publication_id = arguments["publication_id"]
      segment_id = arguments["segment_id"]
      details = client.get_segment_details(publication_id, segment_id)
      return CallToolResult(
          content=[TextContent(type="text", text=json.dumps(details, indent=2))]
      )

• beehiiv_mcp_server.py:157-164 (helper)

  Core helper function in the BeehiivAPI class that performs the HTTP GET request to the Beehiiv API endpoint for segment details.

  def get_segment_details(
      self, publication_id: str, segment_id: str
  ) -> Dict[str, Any]:
      """Get detailed information about a specific segment."""
      data = self._make_request(
          "GET", f"/publications/{publication_id}/segments/{segment_id}"
      )
      return data.get("data", {})

• beehiiv_mcp_server.py:357-374 (registration)

  Registration of the get_segment_details tool in the list_tools() function, including name, description, and input schema.

  Tool(
      name="get_segment_details",
      description="Get detailed information about a specific segment",
      inputSchema={
          "type": "object",
          "properties": {
              "publication_id": {
                  "type": "string",
                  "description": "The publication ID",
              },
              "segment_id": {
                  "type": "string",
                  "description": "The segment ID",
              },
          },
          "required": ["publication_id", "segment_id"],
      },
  ),

• beehiiv_mcp_server.py:357-374 (schema)

  Input schema definition for the get_segment_details tool, specifying required publication_id and segment_id parameters.

  Tool(
      name="get_segment_details",
      description="Get detailed information about a specific segment",
      inputSchema={
          "type": "object",
          "properties": {
              "publication_id": {
                  "type": "string",
                  "description": "The publication ID",
              },
              "segment_id": {
                  "type": "string",
                  "description": "The segment ID",
              },
          },
          "required": ["publication_id", "segment_id"],
      },
  ),