MCP Server

Overview

Heard operates a public Model Context Protocol (MCP) server that exposes Heard’s core capabilities as standard MCP tools.

If you’re building on OpenClaw, you can also install the Public OpenClaw Skills for a zero-config experience. Both paths use the same backend.

Connecting

Point your MCP Host at the Heard MCP server:

Server URL: https://mcp.heard.ai/sse
Transport:  SSE (Server-Sent Events)
Auth:       API key (same key as the REST API)

The server implements the MCP specification:

initialize — Returns server info and capabilities.
tools/list — Auto-discovers all available tools and their schemas.
tools/call — Invokes a tool with the provided parameters.

Authentication

Use the same API key from Settings → Developer → API Keys (see Authentication). Include it as a bearer token during the MCP connection initialization.

Available Tools

`heard-transcribe`

Converts audio to a high-fidelity, speaker-diarized transcript.

Parameter	Type	Required	Description
`audio_url`	string	✅	URL to the audio file (wav, flac, mp3)
`encoding`	string		Audio format. Default: auto-detect
`language_code`	string		BCP-47 language code. Default: `en-US`
`callback_url`	string		Webhook URL for completed transcript

Processing: Asynchronous. Returns a job_id immediately. Use heard-transcribe-status to poll, or provide a callback_url for push notification.

Returns:

{
  "job_id": "job_abc123",
  "status": "processing",
  "poll_url": "https://api.heard.ai/api/v1/ingest/jobs/job_abc123"
}

`heard-transcribe-status`

Polls the status of an async transcription job.

Parameter	Type	Required	Description
`job_id`	string	✅	The `job_id` from `heard-transcribe`

Returns (complete):

{
  "job_id": "job_abc123",
  "status": "completed",
  "transcript_text": "Agent: Hi, how can I help?...",
  "speaker_segments": [...],
  "duration_seconds": 342.5
}

`heard-analyze`

Analyzes a transcript and returns structured conversation intelligence. Optionally accepts customer context for richer, strategic output.

Parameter	Type	Required	Description
`transcript_text`	string	✅	The conversation transcript
`context.customer_name`	string		Customer name
`context.relationship_history`	string		Summary of previous interactions
`context.company_rules`	string		Business rules or playbook excerpts
`context.custom_fields`	object		Additional structured data (ARR, contract dates, tier)
`metadata`	object		Participant names, roles, call context

Processing: Synchronous (~2–5 seconds).

Returns:

{
  "summary": "Customer expressed frustration with recent billing changes...",
  "sentiment": { "overall": "negative", "score": -0.6 },
  "risk_score": 0.82,
  "opportunity_score": 0.15,
  "action_items": [
    {
      "description": "Send billing adjustment confirmation",
      "priority": "high",
      "suggested_owner": "Account Manager"
    }
  ],
  "categories": ["billing", "retention"]
}

MCP vs REST vs OpenClaw Skills

All three paths hit the same Heard backend. Choose based on your setup:

Access Method	Best For	How
MCP Server	Any MCP-compatible agent	Point your MCP Host at `mcp.heard.ai/sse`
REST API	Custom integrations, scripts, webhooks	Call endpoints directly (see Ingestion API)
OpenClaw Skills	OpenClaw developers	Install from ClawHub (see Public OpenClaw Skills)

Same API keys. Same rate limits. Same pricing.

Error Handling

MCP errors are returned as standard JSON-RPC error responses:

Code	Meaning
`VALIDATION_ERROR`	Invalid input (bad format, missing field)
`AUTH_ERROR`	Invalid or expired API key
`RATE_LIMITED`	Too many requests — retry after the indicated interval
`SERVER_ERROR`	Internal error — retry with backoff