MCP
Connect an AI client to your call data with a read-scoped key.
Everything else in this documentation is about getting calls in. This page is the one way to get analysed data back out on demand, and it is not a REST API — it is an MCP server, which an AI client connects to directly.
https://api.calllens.io/api/v1/mcpPoint Claude Desktop, an editor, or anything else that speaks MCP at that URL with a read-scoped
key, and it can ask questions about your calls in plain language.
Getting a key
Mint one in the dashboard under Settings → API keys and tick Read call data. There is no endpoint for creating keys — minting a credential requires a signed-in user, and for this scope that is not merely a policy, it is how the permission model works.
A read key acts as the person who created it. It is not an organization-wide credential. It sees exactly the calls and departments that person sees in the app, and nothing more. If they leave the organization, the key stops working on its next request — there is no revocation step to remember, and no window during which a departed employee's key still reads your data.
That has a practical consequence worth deciding up front: mint the key as the person whose view you want. A key minted by an owner reads the whole organization. A key minted by a team lead reads that team. If several people need different views, they each mint their own.
Connecting a client
Most clients take a URL and a header. In Claude Desktop's configuration file:
{
"mcpServers": {
"call-lens": {
"url": "https://api.calllens.io/api/v1/mcp",
"headers": {
"Authorization": "Bearer clk_{tenant_id}_{secret}"
}
}
}
}X-Api-Key works identically if your client cannot set an Authorization header:
"headers": { "X-Api-Key": "clk_{tenant_id}_{secret}" }The server negotiates protocol versions 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26 and
2024-11-05, which covers every shipping client we know of. It identifies itself as Call Lens.
What the client can do
Eight tools, in two groups. Nothing writes; nothing returns audio.
| Tool | Answers |
|---|---|
search_calls | "Find calls where the customer pushed back on price" |
search_library | The same search across your uploaded reference material |
get_transcript_window | "Show me what was said around that moment" |
aggregate_metric | "How many calls last month, and what was the average score?" |
top_breakdown | "Which objections came up most in July?" |
funnel_outcomes | "What share of calls ended in a commitment?" |
compare_entities | "Compare the two teams on talk ratio" |
resolve_entity | Turns a name a person typed into the thing you actually meant |
The analytic tools read the same pre-computed rollups the dashboard's analytics page reads, so a number an AI client gives you and a number on that screen come from one place and agree. Those rollups are refreshed every fifteen minutes, so a call that finished processing a moment ago may not be counted yet — the figures are consistent, not live.
Answers are scoped, and they say so. When a key's owner cannot see the whole organization, every aggregate comes back marked as narrowed, with a note to that effect, so a partial figure is never presented as an organization-wide one. Denominators travel with the numbers for the same reason: a rate always arrives with the population it was computed over.
Errors
| Status | error | Meaning |
|---|---|---|
| 401 | null | The key is missing, malformed, unknown, or revoked. |
| 401 | no_acting_member | The key is valid, but the person it acts as is no longer an active member. Mint a new key. |
| 403 | insufficient_scope | A valid key without the read scope. data.required_scope names what was needed. |
A key with only ingest cannot reach this endpoint, and a read key cannot submit calls. That
separation is deliberate and works in both directions.
Failures inside a tool — a date range that runs backwards, a metric that does not exist — come back as MCP tool errors carrying a plain-language explanation, not as HTTP failures. Your client will show them to you.
Rate limits
| Bucket | Limit |
|---|---|
| Per key | 60 / minute |
| Per key, burst | 5 / second |
Lower than the ingest limits on purpose. A conversational client makes a handful of calls per question, not hundreds, and each tool call runs a real analytical query.