Connector action

search_events

ReadIdempotent

Search my events

The entry point for almost every workflow. Filter by part of the name, a date range or a status, and get back one row per event with its counts and gallery link. Take the id from here into the per-event tools.

What the client is told

The description an MCP client receives from tools/list, word for word:

Find events by name, date range or status. Returns name, date, status, gallery link and message counts. Never returns guest audio, transcripts or phone numbers.

Annotations

json

{
  "readOnlyHint": true,
  "destructiveHint": false,
  "idempotentHint": true,
  "openWorldHint": false
}

Parameters

Parameter	Type	Required	Description
query	string, up to 80 characters	No	Part of the event name
from	date (YYYY-MM-DD)	No	Earliest event date, inclusive
to	date (YYYY-MM-DD)	No	Latest event date, inclusive
status	one of "draft", "active", "archived"	No	Only events in this status.
limit	integer 1 to 100default 25	No	Maximum number of rows to return.

Input schema as JSON Schema

inputSchema

{
  "type": "object",
  "properties": {
    "query": {
      "description": "Part of the event name",
      "type": "string",
      "minLength": 1,
      "maxLength": 80
    },
    "from": {
      "description": "Earliest event date, inclusive",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "to": {
      "description": "Latest event date, inclusive",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "status": {
      "type": "string",
      "enum": [
        "draft",
        "active",
        "archived"
      ]
    },
    "limit": {
      "default": 25,
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  }
}

Example

Request

tools/call

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "search_events",
    "arguments": {
      "query": "Rivera",
      "from": "2026-11-01",
      "to": "2026-11-30",
      "limit": 10
    }
  }
}

With curl

bash

curl -X POST https://www.happyhearaudio.com/api/mcp \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search_events","arguments":{"query":"Rivera","from":"2026-11-01","to":"2026-11-30","limit":10}}}'

Response

Fake data in a real shape. content[0].text is the same object as a JSON string for clients that read text only.

json

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"events\":[{\"id\":\"7c1f3a2e-9b4d-4e61-8f0a-2d5c6b7e8a91\",\"event_name\":\"Rivera 50th Anniversary\",\"event_date\":\"2026-11-14\",\"status\":\"active\",\"unlocked\":true,\"payment_type\":\"per_event\",\"created_at\":\"2026-10-02T18:21:07.412Z\",\"updated_at\":\"2026-10-29T03:14:55.009Z\",\"gallery_slug\":\"rivera-50th-anniversary\",\"gallery_url\":\"https://www.happyhearaudio.com/g/rivera-50th-anniversary\",\"has_share_code\":false,\"gallery_sent\":true,\"gallery_first_opened_at\":\"2026-11-16T15:02:41.000Z\",\"download_enabled\":true,\"callin_enabled\":true,\"callin_start_date\":\"2026-11-07\",\"callin_end_date\":\"2026-11-21\",\"clean_level\":\"standard\",\"date_changes_remaining\":2,\"messages_total\":42,\"messages_ready\":39,\"messages_cleaning\":2,\"messages_waiting\":0,\"messages_needs_attention\":1,\"messages_hidden_by_operator\":1,\"unique_visitors\":63,\"total_plays\":217,\"total_downloads\":11}],\"count\":1,\"truncated\":false}"
      }
    ],
    "structuredContent": {
      "events": [
        {
          "id": "7c1f3a2e-9b4d-4e61-8f0a-2d5c6b7e8a91",
          "event_name": "Rivera 50th Anniversary",
          "event_date": "2026-11-14",
          "status": "active",
          "unlocked": true,
          "payment_type": "per_event",
          "created_at": "2026-10-02T18:21:07.412Z",
          "updated_at": "2026-10-29T03:14:55.009Z",
          "gallery_slug": "rivera-50th-anniversary",
          "gallery_url": "https://www.happyhearaudio.com/g/rivera-50th-anniversary",
          "has_share_code": false,
          "gallery_sent": true,
          "gallery_first_opened_at": "2026-11-16T15:02:41.000Z",
          "download_enabled": true,
          "callin_enabled": true,
          "callin_start_date": "2026-11-07",
          "callin_end_date": "2026-11-21",
          "clean_level": "standard",
          "date_changes_remaining": 2,
          "messages_total": 42,
          "messages_ready": 39,
          "messages_cleaning": 2,
          "messages_waiting": 0,
          "messages_needs_attention": 1,
          "messages_hidden_by_operator": 1,
          "unique_visitors": 63,
          "total_plays": 217,
          "total_downloads": 11
        }
      ],
      "count": 1,
      "truncated": false
    }
  }
}

Errors

Each of these comes back as a normal JSON-RPC result with isError: true and the message as its single text item. Arguments the schema rejects are a JSON-RPC -32602 error instead. See Errors for the HTTP-level refusals that happen before any tool runs.

Message	When
Could not read events right now.	A database read failed. Retry after a short wait.

Limits

60 requests per minute per operator across all actions, answered with HTTP 429 and a Retry-After header past that.
No daily cap. Read actions are not logged and not counted.

Worth knowing

Rows come newest event date first; events without a date sort last.
The name match is a case-insensitive substring. Wildcard characters in query are matched literally.
truncated is true when exactly limit rows came back, so there may be more: narrow the filter or raise limit (100 at most).
Only the signed-in operator's events are visible. Row-level security enforces this below the server, not in this code.