Home / Integrations

Anweshna API & MCP integration guide

Two ways to reach Anweshna from your own systems: a REST API for server-to-server automation, and a hosted MCP server that makes screening available as tools inside Claude, ChatGPT and any agentic deal workflow.

What you get back is risk screening, not due diligence. Anweshna scores documents across 15 risk categories and flags what a reviewer should look at. It performs no independent verification and no primary research. Treat a clean result as “nothing surfaced in this document”, never as “this deal is clean”.

Authentication

Every request carries your API key, either as an X-API-Key header or as Authorization: Bearer <key>. Keys are issued on signup and delivered by email; team members get their own sub-keys from the portal, which carry that member’s role. 

curl https://anweshna.com/api/v1/documents/usage \
  -H "X-API-Key: your-key-here"

Keys must never appear in a URL — there is no query-parameter fallback, because URLs end up in access logs, browser history and Referer headers.

MCP server

The MCP endpoint is https://anweshna.com/mcp/, over the streamable HTTP transport. Point any MCP-capable client at it and pass your API key as a header. 

{
  "mcpServers": {
    "anweshna": {
      "url": "https://anweshna.com/mcp/",
      "headers": { "X-API-Key": "your-key-here" }
    }
  }
}

The server is stateless, so there is no session to keep alive and no affinity requirement — each call stands on its own.

MCP tools

ToolWhat it does
screen_document Upload one document and score it. Pass the file as content_base64 (PDF, DOCX, TXT, CSV) or as plain text. Returns the overall score, rating, blocked flag and per-category findings.
get_analysis Fetch the stored analysis for a document this account has already screened. Read-only.
bulk_screen Upload and score up to 25 documents as one batch. Waits for text extraction, then starts scoring and returns job ids; poll get_bulk_status until the batch finishes. If that wait times out, call it again with bulk_job_id instead of documents to score the batch you already uploaded — re-uploading would spend your quota twice.
get_bulk_status Poll a batch started by bulk_screen until it finishes.

A large or unusually dense document is routed automatically to the chunk-parallel Deep Scan engine. When that happens screen_document returns status: "processing" with a job handle rather than blocking — poll get_analysis until the status changes.

REST endpoints

The MCP tools are a thin layer over these. Use them directly for server-to-server work.

EndpointPurpose
POST /api/v1/documents/uploadUpload a single document (multipart).
POST /api/v1/analysis/{document_id}Score an uploaded document.
GET /api/v1/analysis/{document_id}Retrieve a stored analysis.
POST /api/v1/documents/bulk-uploadUpload up to 25 documents.
POST /api/v1/analysis/bulk-analyzeScore a batch.
GET /api/v1/documents/usageCurrent plan, quota and enabled features.
GET /api/v1/reports/{document_id}/downloadDownload a report (Markdown, JSON, PDF or DOCX, subject to plan).

This is the externally supported surface. Anweshna does not publish a generated OpenAPI schema in production: it would expose admin, billing and internal routes alongside these, which is why /docs is disabled there.

Errors you must handle

Never treat a failed scan as a clean result. The states below mean scoring did not happen. Over MCP each one arrives as an explicit tool error, not an empty finding list — handle them, rather than reporting the document as clear.
StatusMeaningWhat to do
402 Subscription inactive, or the plan’s upload quota is used up. Renew or upgrade. Retrying will not help.
403 The key’s role may not do this — viewers cannot upload. Use a key with the right role.
422 The document is too large or too dense to score in a single pass. Run Deep Scan, or re-send with force_precision to accept a truncated scan. The response says which applies.
503 The scoring engine was unavailable. Re-upload the document. Retrying the same request unchanged fails the same way.

Plans and limits

The API and the MCP server are available on every paid plan. Batches are capped at 25 documents per request. Upload volume, deal-room count and export formats vary by plan — see pricing, or call GET /api/v1/documents/usage to read the live figures for your own account.

Over MCP, request size binds before the document count does. Files travel base64-encoded inside the JSON-RPC request, and base64 adds about a third, so a single screen_document call — or a whole bulk_screen batch — must stay under 32 MB in total, roughly 24 MB of actual document. Send fewer, larger files per batch rather than filling all 25 slots. A request over that limit is refused by the transport with an HTTP 413 before the tool runs, so it arrives as a raw HTTP error rather than a normal tool error. The REST endpoints take up to 50 MB per file and are the right route for anything larger.

Rate limits apply per account. Documents and their extracted text are encrypted at rest with a per-client key, and every write is recorded in your audit log.

Self-hosting the MCP server? If you run Anweshna behind your own domain, set MCP_ALLOWED_HOSTS to that domain. The MCP transport validates the Host header as DNS-rebinding protection and rejects anything unlisted with a 421, which resembles neither an authentication nor a routing failure.
Anweshna Demo