@ear3/mcp

MCP server for Ear3 — lets any MCP client (Claude Code, Claude Desktop, Cursor, …) create, deploy, edit, and analyze AI voice interviews. It is the same thin layer over the Ear3 /api/v1 HTTP API that the ear3 CLI uses — and it shares the CLI's login, so authenticating once covers both.

Install

Claude Code:

claude mcp add ear3 -- npx -y @ear3/mcp

Or in a project's .mcp.json (Claude Code, Cursor, and most clients):

{
  "mcpServers": {
    "ear3": {
      "command": "npx",
      "args": ["-y", "@ear3/mcp"]
    }
  }
}

Authentication

The server resolves a secret key itself — it never appears in the model's context:

1. EAR3_CONFIG_CLI_KEY environment variable (set it in the server config env block), or
2. the CLI login store ~/.ear3/config.json — run npx @ear3/voice-config-cli login once and both the CLI and this server are authenticated.

EAR3_API_BASE overrides the API host (dev/staging).

Tools

| Tool | What it does | |---|---| | ear3_create_interview | prompt → generated questions, deployed, live URL + pk key | | ear3_list_interviews | deployed interviews (id = dpl_… = SDK interviewId) | | ear3_get_questions | ordered question list of an interview | | ear3_get_interview_config | full normalized flow JSON for surgical edits | | ear3_edit_interview | regenerate from a prompt / replace flow / rename | | ear3_deploy_interview | deploy a draft → dpl_… + public URL | | ear3_list_responses | responses (transcripts opt-in to save context) | | ear3_ask_insight | AI answer over responses, with verbatim quotes | | ear3_get_session | one session by id | | ear3_get_publishable_key | workspace pk_… key (browser-safe) | | ear3_get_interview_format | flow JSON schema reference |

Two ids: the interview id (edit/config/deploy tools) and the deployment id dpl_… (the interviewId all SDKs take; responses and insights tools). Tool descriptions say which one they expect.

Development

pnpm --filter @ear3/mcp build
pnpm --filter @ear3/mcp test
pnpm --filter @ear3/mcp inspect   # MCP Inspector against the local build

Transport is stdio — stdout is the protocol channel, so never console.log in server code; use console.error. A remote Streamable HTTP variant (with OAuth and mandatory Origin validation) is planned as a separate deployment of this same package.

Agent-facing docs: AGENTS.md → llms.txt. Eval questions for testing agent usage live in evals/.