Skip to main content

Tools and details

Each MCP tool calls one Public API operation as the user who created your API key, so it returns the same data and follows the same rules as the REST API.

Tools​

All tools are read-only.

  • contacts_search searches your contacts. It accepts the filters of GET /api/v1/contacts: searchTerm, status, sourceKind, assignedWorkflowId, addedSince, and addedBefore.
  • contact_get reads one contact by its Harmony id.
  • contact_get_by_external_id reads one contact by its sourceKind and externalId.
  • contact_calls_list lists the calls of the contact with that sourceKind and externalId, oldest first.
  • call_transcript_get reads one call's transcript by the call's id. The transcript is empty until the call's report is ready, and stays empty for a call that has no transcript.
  • workflows_list lists your workflows.

The list tools return one page at a time. They accept limit, and nextToken from the previous page.

Other clients​

Any MCP client that connects over Streamable HTTP and can send an Authorization: Bearer harmony_pk_... header works.

  • ChatGPT can't connect yet. It connects only through OAuth sign-in, and Harmony's OAuth support is still in progress.
  • Clients that run in a web browser can't connect. The server answers 403 to any request with an Origin header.

Errors​

When a Public API operation fails, the tool returns an error result whose text is the error body, including the code and requestId.

A missing, unknown, or revoked key fails the whole request with 401, so the client can't connect.

Keys and data​

  • The client can read everything the key's creator can read through these tools, including contact details and call transcripts. Create a separate key for each person and client, so you can revoke one without breaking the others.
  • Everything a tool returns is sent to the model your client uses, under that provider's terms.
  • Tool results contain text written by your contacts and teammates, such as names, notes, and what was said on calls. Treat it as untrusted input to the model, especially when the client can also act through other tools.