> ## Documentation Index
> Fetch the complete documentation index at: https://docs-corpus.apart.io/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Connect compatible agents to read-only Corpus tools for United States, India, and internal China data.

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.

> [!WARNING]
>
> **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:

```text theme={"dark"}
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.

> [!WARNING]
>
> 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:

```bash theme={"dark"}
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](https://code.claude.com/docs/en/mcp) for configuration scopes and troubleshooting.

## Cursor

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

```json theme={"dark"}
{
  "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](https://cursor.com/docs/mcp.md) 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](https://help.openai.com/en/articles/12584461-developer-mode-apps-and-full-mcp-connectors-in-chatgpt-beta) | 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](https://docs-corpus.apart.io/quickstart.md) and [OpenAPI specification](https://docs-corpus.apart.io/openapi.json).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.