MCP

The Model Context Protocol surface at https://mcp.earshot.dev/mcp. Every capability available in the dashboard is also a tool here, with the same auth model. The agent surface is first-class.

Discovery

GET https://earshot.dev/oauth/.well-known/oauth-authorization-server

Returns the OAuth 2.1 server metadata: issuer, authorization endpoint, token endpoint, registration endpoint, response/grant types, PKCE methods, scopes.

Auth

Two paths, depending on what you are:

Project key (`pk_*`) — for the widget + scripts

The seeded API key for a project, shown once on the project settings page. Lets the bearer call project-scoped tools only (read/write feedback, project context, integrations within one project).

Authorization: Bearer pk_live_xxxxxxxxxxxxxxxx

OAuth JWT — for agents

Spec-standard OAuth 2.1 + Dynamic Client Registration + PKCE.

POST /api/oauth/register — register a client. Returns client_id (and client_secret unless you registered as a public client with token_endpoint_auth_method=none).
Direct the user to /oauth/authorize?client_id=...&redirect_uri=...&response_type=code&code_challenge=...&code_challenge_method=S256&state=...&scope=read+write. They log in (magic link if not already), pick which team + which MCP tools the client may use, and approve.
We redirect back to redirect_uri?code=...&state=....
POST /api/oauth/token with grant_type=authorization_code, code, redirect_uri, client_id, client_secret, code_verifier. Returns access_token (JWT, 1h TTL), refresh_token (opaque, 30d, rotated on use).

Authorization: Bearer <JWT>

A JWT gives access to both project-scoped tools (acting on the user's chosen team's first project) and user-scoped tools (create_team, create_project, rotate_api_key, list_projects).

tools/list is filtered to the selected_tools the user granted at consent; tools/call refuses anything outside that set.

Transport

Streamable HTTP (@modelcontextprotocol/sdk v1.x web-standard transport). JSON-RPC payload. Stateless / non-streaming for tool calls that complete synchronously.

POST /mcp
Content-Type: application/json
Accept: application/json, text/event-stream
Authorization: Bearer ...

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "list_feedback", "arguments": { "limit": 5 } }
}

Tools

13 project-scoped + 4 user-scoped = 17 total.

Feedback

Tool	Purpose
`list_feedback`	Paginated list, filter by status
`get_feedback`	Full record incl. transcript, LLM-derived title/summary, context, federation, identity, external_ref
`list_comments`	Comments thread
`resolve_feedback`	Mark resolved + add audit comment

Project context

Tool	Purpose
`set_project_context`	Push/replace/merge the project brief
`get_project_context`	Current brief + rendered preview
`validate_project_context`	Dry-run (token budget + sections present)
`list_project_context_revisions`	Audit log

Integrations

Tool	Purpose
`suggest_integrations`	Advisor: agent sends what it found, we return a ranked plan
`connect_integration`	Commit one integration, credentials encrypted at rest
`test_integration`	Real network smoke-test against the provider
`list_integrations`	Per-project listing without credentials

User-scoped (OAuth JWT required)

Tool	Purpose
`create_team`	New team + add caller as admin
`create_project`	New project under a team; returns the `pk_*` once
`rotate_api_key`	Rotate a project's `pk_*`
`list_projects`	Projects in this JWT's scope

Tool details

Each tool's full input schema is returned by tools/list (JSON Schema draft 2020-12). Try:

curl https://mcp.earshot.dev/mcp \
  -H 'Authorization: Bearer pk_live_...' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Errors

Per JSON-RPC, tool-call failures come back as result.isError: true with a text-content explanation, not a JSON-RPC error envelope. Auth failures and protocol errors return JSON-RPC errors at the transport layer.

What's deferred

Per-tool max_tokens parameter + truncation hints (vision §6 AX baseline).
MCP UI Apps for inline-rendered context in agent chats.
SSE streaming for long-running tools.

MCP