AskElephant MCP

A Cloudflare Worker that lets Meticulosity staff dig into AskElephant call transcripts from claude.ai, on the web and on mobile.

Live: https://askelephant-mcp.<your-subdomain>.workers.dev/mcp Deploy your own: SETUP.md Setup for staff: docs/install-guide.md How to ask for things: docs/usage-examples.md

Why this exists

AskElephant ships an MCP server, but it runs locally over stdio. That works for Cursor, VS Code, Windsurf and Claude Desktop, and it does nothing for claude.ai, which can only talk to a hosted endpoint. Our team works in claude.ai, so transcripts were out of reach there. This Worker is the hosted endpoint.

It is read-only. Every path to AskElephant is a GET. Nothing in this codebase can change, delete, or create anything in your AskElephant account.

The problem it actually solves

Transcripts are enormous. Measured across the real corpus:

	characters	approx tokens
average call	41,518	10,400
largest measured	129,088	32,300

Handing whole transcripts to a model costs about 415,000 tokens for a forty-call search, which does not fit in a 200,000-token context window. So the design principle is:

The Worker does the reading. Claude does the thinking.

Transcript text never reaches the model unless someone explicitly asks for it. A forty-call search costs roughly 12,400 tokens instead of 415,000, because the Worker fetches the transcripts, scans them itself, and returns only the matching passages.

The five tools, cheapest first

Tool	What it does	Cost
list_meetings	Compact rows: id, title, date, duration, companies	~30 tokens per row
list_companies / list_contacts	Name to id lookup for the filters	negligible
search_transcripts	Searches inside transcripts, returns short excerpts with speaker and timestamp	~12,400 tokens for 40 calls
get_transcript	Full raw text, in chunks	up to ~32,000 tokens for one call

The tool descriptions themselves steer Claude toward the cheap ones. That is deliberate: get_transcript describes itself as expensive and points at search_transcripts first.

search_transcripts requires a narrowing filter (a date range, a company, a contact, or title terms). Without one it would scan the entire corpus of 3,705 engagements, so it refuses instead.

Architecture

claude.ai  --MCP over Streamable HTTP-->  Worker  --REST-->  app.askelephant.ai/api/v2
                                            |
                                            +-- KV cache (transcripts, 90 day TTL)

Stateless apart from the cache. No database, no ingestion pipeline, no sync job. The Worker is fully correct with the cache empty; the cache only saves refetching.

Login is Cloudflare Access over OIDC with PKCE. @cloudflare/workers-oauth-provider makes the Worker its own OAuth server so claude.ai can register itself, and delegates the actual login upstream to Cloudflare Access. Access is restricted to the named individuals in CONFIG.allowedEmails.

Repo layout

Path	What
src/config.ts	Every deployment-specific value. The seam a fork changes.
src/askelephant.ts	The only code that talks HTTP to AskElephant
src/meetings.ts	Listing and the compact projection
src/cache.ts	Read-through KV transcript cache
src/search.ts	Pure excerpt scanner, no IO
src/search_meetings.ts	Search orchestration, caps and guards
src/mcp.ts	The five tools
src/access_handler.ts	Cloudflare Access OIDC login
docs/api-notes.md	Verified AskElephant API reference. See below.

docs/api-notes.md is the valuable part

AskElephant's v2 API is not publicly documented. docs/api-notes.md records what we established by probing it, with the raw commands and raw output, including where an earlier conclusion was wrong and how it was corrected. Some of it is genuinely surprising:

• The auth header takes the raw key with no Bearer prefix
• processing_status reports PENDING for every engagement ever, including calls from 2023, so it is useless as a filter
• search matches titles only, never transcript bodies, which is the entire reason the excerpt scanner exists
• Date filters reject a plain 2026-01-01 and require a full UTC datetime
• filter[company_ids] returns a 400 without an operator; it needs filter[company_ids][in]
• There is no summary and no action-items content: the transcript is all you get

Every one of those cost us a bug or a wrong assumption first. Read that file before changing anything that talks to the vendor.

Development

npm install        # requires the committed .npmrc, see below
npm test           # 143 tests, no network access
npm run typecheck

Why .npmrc exists. Plain npm install fails with ERESOLVE because wrangler, agents and @cloudflare/workers-types declare peer ranges that npm's strict resolver will not reconcile, even though every individual range is satisfiable. .npmrc sets legacy-peer-deps=true, which restores npm's pre-v7 behaviour and changes which versions actually install not at all. Without that file the build is not reproducible on a clean checkout.

Tests never touch the network. Every AskElephant response in the suite comes from a recorded fixture built from real probe output.

Deploying

The Worker lives on the Meticulosity Cloudflare account. Note that a global CLOUDFLARE_API_TOKEN in a shell profile may point somewhere else entirely, so pass the token explicitly:

export CLOUDFLARE_API_TOKEN=$(security find-generic-password -s cloudflare_api_token -w)
export CLOUDFLARE_ACCOUNT_ID=<YOUR_CLOUDFLARE_ACCOUNT_ID>
npx wrangler deploy

Secrets are set with wrangler secret put and never live in this repo: ASKELEPHANT_API_KEY, ACCESS_CLIENT_ID, ACCESS_CLIENT_SECRET, ACCESS_ISSUER, COOKIE_ENCRYPTION_KEY.

Data retention

Transcripts the Worker reads are cached in Cloudflare KV with a 90 day expiry (CONFIG.cacheTtlDays). That is a retention decision, not a performance knob: without it the Worker would keep a permanent second copy of every transcript it ever read, outside AskElephant's own retention controls. Lower it if your client agreements require it.

Access and offboarding

Access is an explicit list of named people in CONFIG.allowedEmails, enforced twice: the Cloudflare Access policy names the same individuals, and the Worker re-checks the identity before registering any tools.

It is not domain-wide, and that is a correction rather than a preference. We first granted the whole @example.com domain, reasoning that revocation could be delegated upstream because everyone uses a company-controlled Claude account, so deprovisioning that account would take the connector with it. That reasoning is wrong. The connector can be added from any Claude account, including a personal one, because the only identity the Worker ever sees is the Cloudflare Access identity. This was demonstrated during setup, when two separate Claude clients registered against the same address.

Revoking someone

Removing a person from CONFIG.allowedEmails and from the Access policy stops them getting a new grant. It does not touch a grant they already hold, which lives in OAUTH_KV and keeps working until it expires.

To cut someone off immediately:

scripts/revoke.sh someone@example.com   # deletes their grants and tokens
scripts/revoke.sh --list                     # show every live grant

Do all three: revoke the grant, remove them from CONFIG.allowedEmails and redeploy, and remove them from the Cloudflare Access policy. The first cuts off the session they have; the other two stop them logging back in.