MCP Server

Corpus MCP gives agents a read-only tool layer over the authoritative Corpus API. The MCP process does not read Postgres or Blob Storage directly: every tool call goes through the API, so credential scopes, jurisdiction boundaries, point-in-time behavior, response contracts, and processing states remain authoritative.

Private beta. The remote endpoint currently relies on API-key headers or a pre-provisioned bearer token. Standards-based MCP OAuth discovery is not live yet, so use a client that can attach a custom header. China data is internal-only and is not licensed for redistribution.

Endpoint

Corpus uses the Streamable HTTP transport:

https://mcp-corpus.apart.io/mcp

The server implementation supports MCP 2026-07-28 with JSON responses and per-request protocol metadata. Modern clients can call tools without initialization; server/discover is optional. The same endpoint retains legacy initialization support without persistent HTTP sessions. It exposes only read tools; it cannot write documents, place trades, change source data, or run governed exports.

Available tools

US, India, and China tools use separate names and identifiers. Never mix a CIK, ticker, SEC accession number, ISIN, annual-report artifact ID, judgment ID, or mainland China security code across jurisdictions.

Jurisdiction	Available tool families
United States	Catalog discovery; company resolution; daily prices; normalized and as-reported financials; the SEC fundamentals ledger; filing metadata, bounded content, filing items, manifests, and XBRL files; exact PDS submission bytes and normalized PDS text; Form 4 transactions; Form 13F holdings; corporate events; EDGAR coverage; and filing search
India	Securities; daily prices; annual-report metadata and bounded text; publisher-feed news and categories; judgment metadata and bounded text; court facets; and document search
China	Internal-only A-share security listing and resolution, plus unadjusted daily prices keyed by exchange-qualified codes such as `sh.600519`

Binary files and tabular exports remain available through the REST API. Corpus MCP does not expose administrative or write routes.

Query filters

All filters are optional and apply before pagination. Different filters intersect, while values within filing_types match any listed form. as_of independently controls what was known at a given time; it does not replace record-date filters. Date/year ranges include both endpoints. Publication-date filters cover whole UTC days and exclude unknown publication dates.

Tools	Additional parameters
SEC text search	`cik`, `accession_number`, `filing_types`, `filing_date_start`, `filing_date_end`, `report_date_start`, `report_date_end`, `item`
Financial statements	`period_end_start`, `period_end_end`
Fundamental facts	`period_end_start`, `period_end_end`, `fiscal_year`, `filing_types`
SEC filing list	`accession_number` (no ticker or CIK required for exact accession lookup)
India annual reports	`bse_code`, `year_start`, `year_end`
India judgments	`decision_date_start`, `decision_date_end`, `case_number`, `cnr`
India news	`published_start`, `published_end`, `source_id`, `query`

SEC search accepts either filing_type or filing_types, not both. India document search also accepts the report and judgment filters above: report-specific filters require document_type="annual_report"; judgment-specific filters require document_type="judgment". India search matches company names and case titles, not document bodies. News query searches titles and summaries; source_id currently selects a feed collection, not an individual publisher. Invalid or reversed ranges return a validation error. For example, an agent can search for liquidity in Item 1A of Apple’s 10-K and 10-K/A filings filed between 2023 and 2024, with a separate knowledge cutoff of January 1, 2025.

Authentication and scopes

Send the same provisioned key used by the REST API in the X-API-KEY header. A pre-provisioned OIDC token can instead use the Authorization: Bearer header. Use a least-privilege credential:

Operation	Required scopes
US reads, including PDS reads	`us:read`
US filing search	`us:read` and `search:read`
India reads	`india:read`
India document search	`india:read` and `search:read`; judgment results also require `litigation:read`
India judgment reads	`india:read` and `litigation:read`
Internal China reads	`china:read`

The remote server never falls back to an operator or process-wide API key. Missing credentials are rejected before MCP dispatch; invalid credentials and insufficient scopes are rejected by the Corpus API when a tool executes.

Treat the credential as a secret. Keep it in a user-level MCP configuration or environment variable, never in a committed project file.

Claude Code

Set the key in your shell, then add the remote HTTP server:

export CORPUS_API_KEY="your_api_key_here"

claude mcp add --transport http corpus \
  "https://mcp-corpus.apart.io/mcp" \
  --header "X-API-KEY: $CORPUS_API_KEY"

Run /mcp inside Claude Code to inspect the connection and discovered tools. See Claude Code’s MCP documentation for configuration scopes and troubleshooting.

Cursor

Add the server to your user-level ~/.cursor/mcp.json configuration:

{
  "mcpServers": {
    "corpus": {
      "url": "https://mcp-corpus.apart.io/mcp",
      "headers": {
        "X-API-KEY": "${env:CORPUS_API_KEY}"
      }
    }
  }
}

Launch Cursor from an environment where CORPUS_API_KEY is available, then review and enable the Corpus tools in MCP settings. See Cursor’s MCP documentation for user- and project-level configuration locations.

Example prompts

“Resolve Apple, then show its last four annual income statements with filing accessions.”
“Find Apple’s 2025 10-K and return Item 1A with source offsets.”
“Read a bounded window from an accession’s exact active PDS submission and retain its hashes.”
“Compare normalized PDS text with canonical filing content without treating one as a substitute for the other.”
“Show Reliance Industries prices for October 2025 using its ISIN.”
“Find 2022 Reliance annual reports and summarize only the available extracted text.”
“Search Indian judgments for retrospective taxation and cite judgment IDs.”
“For internal research, show unadjusted Kweichow Moutai prices using sh.600519.”

Content and processing limits

Filing, annual-report, and judgment text is windowed before it is serialized to MCP. Continue with the returned offset instead of requesting an entire large document in one tool call. Filing items and event text are also capped per record; target a specific item and continue from its returned offset when more text is needed. The MCP adapter also rejects an upstream response that exceeds its configured safety ceiling. For a raw filing whose API response uses encoding=base64, request window offsets and lengths in multiples of four. Each aligned page can then be decoded independently; content_hash continues to identify the complete source object, not the page. The two PDS tools are explicit evidence surfaces. One returns bounded base64 byte windows from an exact active SEC PDS submission; the other returns a separately proven normalized derivative. Preserve their archive generation, source identity, hashes, parser identity, byte range, and primary-document evidence. Neither surface silently replaces canonical filing content. Known SEC filing metadata can exist before source bytes, normalized text, or parsed items finish processing. In that state, the underlying API can return 503 and a retry interval. Agents should report the pending state rather than treating the filing as absent. The fundamentals tool exposes Corpus’s point-in-time serving projection. It is not a lossless copy of every EDGAR context and unit fact and can coalesce same-day duplicates. Use accession numbers, filing dates, knowledge-time fields, and source URLs retained in the result when auditing an answer. China prices are unadjusted. Suspended sessions are represented by rows with null prices and must not be interpolated or interpreted as zero-return sessions.

Client compatibility

Client	Private-beta status
Claude Code	Supported with `X-API-KEY` header configuration
Cursor	Supported with a remote HTTP server and custom header
ChatGPT apps	Not yet published; requires standards-based OAuth discovery and refresh-token support
Claude.ai and remote Claude Desktop connectors	Not yet published; requires standards-based OAuth

For binary responses, client generation, and the complete request surface, continue to use the REST Quick Start and OpenAPI specification.

Get started

Shared API

Account and credits

Guides

Endpoint

Available tools

Query filters

Authentication and scopes

Claude Code

Cursor

Example prompts

Content and processing limits

Client compatibility

​Endpoint

​Available tools

​Query filters

​Authentication and scopes

​Claude Code

​Cursor

​Example prompts

​Content and processing limits

​Client compatibility

Endpoint

Available tools

Query filters

Authentication and scopes

Claude Code

Cursor

Example prompts

Content and processing limits

Client compatibility