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

Tool	What 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.

Endpoint	Purpose
`POST /api/v1/documents/upload`	Upload 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-upload`	Upload up to 25 documents.
`POST /api/v1/analysis/bulk-analyze`	Score a batch.
`GET /api/v1/documents/usage`	Current plan, quota and enabled features.
`GET /api/v1/reports/{document_id}/download`	Download 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.

Status	Meaning	What 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, and clean-room documents are restricted to the clean team.	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.

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.