Connector action

start_cleaning

WriteIdempotent30 calls per day

Start cleaning an event

Runs Clean All on an event, exactly as the button on the event page does: every message that is not clean yet is sent to the cleaner. Idempotent: a second call while a run is in progress reports already_running and starts nothing.

What the client is told

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

Runs "Clean All" on an event you own: starts audio cleaning for every message not cleaned yet. Safe to call twice; if a clean is already running it says so instead of starting another. Never re-cleans finished messages.

Annotations

json

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

Parameters

Parameter	Type	Required	Description
event_id	string (uuid)	Yes	The event id, as returned by search_events or create_event.

Input schema as JSON Schema

inputSchema

{
  "type": "object",
  "properties": {
    "event_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    }
  },
  "required": [
    "event_id"
  ]
}

Example

Request

tools/call

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "start_cleaning",
    "arguments": {
      "event_id": "7c1f3a2e-9b4d-4e61-8f0a-2d5c6b7e8a91"
    }
  }
}

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":"start_cleaning","arguments":{"event_id":"7c1f3a2e-9b4d-4e61-8f0a-2d5c6b7e8a91"}}}'

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": "{\"event_id\":\"7c1f3a2e-9b4d-4e61-8f0a-2d5c6b7e8a91\",\"already_running\":false,\"started\":3,\"queued\":0,\"already_clean\":39,\"note\":\"Cleaning takes a few minutes per message and finishes in the background. Ask get_event for progress.\"}"
      }
    ],
    "structuredContent": {
      "event_id": "7c1f3a2e-9b4d-4e61-8f0a-2d5c6b7e8a91",
      "already_running": false,
      "started": 3,
      "queued": 0,
      "already_clean": 39,
      "note": "Cleaning takes a few minutes per message and finishes in the background. Ask get_event for progress."
    }
  }
}

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
No event with that id in your account.	The id is not an event in the signed-in account, or the event was deleted.
<the unlock message from the dashboard>	The event is still locked (not paid for and not covered by the free event or a subscription). Payment happens in the dashboard, never here.
Audio cleaning is not available right now.	The cleaning service is not configured on the server. Rare; nothing to do on the client side.
Daily limit reached: your AI assistant has already made 30 cleaning requests in the last 24 hours, so nothing was changed. You can do this in your Happy Hear dashboard now, or ask again tomorrow. If this looks wrong, email hello@happyhearaudio.com.	The account already made 30 calls to this tool in the last 24 hours. The refusal is logged and does not count toward the limit.
Something went wrong on our side. Try again in a minute.	An unexpected failure inside the write. Nothing was changed.

Limits

60 requests per minute per operator across all actions, answered with HTTP 429 and a Retry-After header past that.
30 successful calls per operator in any rolling 24 hours, the same on every plan. The refusal does not count toward the cap.

Worth knowing

There is no force flag by design. A forced re-clean would re-bill every finished message.
queued is the count the cleaning vendor refused for the moment; the server continues them on its own.
The call returns as soon as the work is started. Poll get_event or get_event_audio_status for completion.
Billed the same way as the dashboard button. The operator sees nothing new on their invoice because of the connector.

Claude and ChatGPT ask the operator to approve a write action before it runs unless the operator turns that off on their side. Design your client the same way: confirm before calling.