> ## Documentation Index
> Fetch the complete documentation index at: https://doc.astreus.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP server
> Use Astreus inside Claude, Cursor, VS Code or any MCP client — ask questions in plain English, get numbers with SEC filings cited.
Astreus is an **MCP server**: AI assistants can connect to it and work directly with the
platform's structured, traceable financial data — statements, segments, filings, decks,
transcripts, guidance, events, news, ownership, macro and the claim graph, across the US,
the Gulf, Japan, Taiwan, Korea and Europe. Once connected, you don't write API calls — you
ask questions:
> "Did NVIDIA beat its data-center guidance last quarter? Cite the filings."
The assistant chains the tools itself (resolve the company → pull segment revenue → pull the
guidance scorecard → trace the numbers to their filings) and answers with accession numbers
next to every figure.
There are 18 tools, all **read-only**, covering the live coverage inventory, search, standardized financials,
fact-level citations, filings and their text sections, 8-K events, the news tape,
earnings-call transcripts, guidance scorecards, point-in-time macro, and the causal claim graph.
A connected app can never see your API keys, billing or account — those surfaces
don't exist on the MCP side.
## Connect your client
No API key needed — you approve the connection with your Astreus sign-in (OAuth).
In Claude, open **Settings → Connectors → Add custom connector** and paste:
```
https://astreus.ai/api/mcp
```
Claude sends you to Astreus. Sign in (or you already are), review what's being
granted — read-only data access, metered on your plan — and click **Approve**.
Back in Claude, enable the connector in the chat's tools menu and ask a question.
The connection works on Claude mobile too, and you can revoke it anytime from
Claude's connector settings.
One command in your terminal, using an API key from the
[Developers page](https://astreus.ai/developers):
```bash theme={null}
claude mcp add --transport http astreus https://astreus.ai/api/mcp \
--header "Authorization: Bearer pk_live_..."
```
Run `/mcp` inside a session to see the server and its tools, then just ask.
Claude Desktop runs the local stdio server, which ships with the
[CLI](/cli):
```bash theme={null}
npm install -g astreus-cli
```
Then add to `claude_desktop_config.json` (**Settings → Developer → Edit Config**):
```json theme={null}
{
"mcpServers": {
"astreus": {
"command": "astreus",
"args": ["mcp"],
"env": { "ASTREUS_API_KEY": "pk_live_..." }
}
}
}
```
Restart Claude Desktop; Astreus appears under the tools icon.
In `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global) — either transport:
```json theme={null}
{
"mcpServers": {
"astreus": {
"url": "https://astreus.ai/api/mcp",
"headers": { "Authorization": "Bearer pk_live_..." }
}
}
}
```
For Copilot agent mode, in `.vscode/mcp.json`:
```json theme={null}
{
"servers": {
"astreus": {
"type": "http",
"url": "https://astreus.ai/api/mcp",
"headers": { "Authorization": "Bearer pk_live_..." }
}
}
}
```
Any MCP client works. Two transports, same tools:
* **Streamable HTTP**: `https://astreus.ai/api/mcp` — authenticate with
`Authorization: Bearer pk_live_...` (or `X-API-KEY`), or via the OAuth flow advertised
at `/.well-known/oauth-protected-resource/api/mcp` (dynamic registration + PKCE).
* **stdio**: `astreus mcp` (from `npm i -g astreus-cli`), key via `ASTREUS_API_KEY`.
From the Claude API, no client code at all:
```json theme={null}
{
"mcp_servers": [{
"type": "url",
"url": "https://astreus.ai/api/mcp",
"name": "astreus",
"authorization_token": "pk_live_..."
}]
}
```
Discovery manifest: [`/.well-known/mcp.json`](https://astreus.ai/.well-known/mcp.json).
Good first prompts: *"What was Apple's gross margin trend over the last 8 quarters? Cite each
figure."* · *"Summarize the newest 8-K from Tesla."* · *"What did NVIDIA's management promise
on the last earnings call, and what's their guidance hit rate?"* · *"Show US unemployment as
it was known in March 2020."*
## The tools
| Tool | What it returns |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `get_coverage` | The live inventory: every market served with its exchanges, companies, history depth, completeness and periods held per data type, plus universe totals. The answer to "do you cover…?" — no key needed. |
| `search` | Resolve a name → companies (ticker + CIK or platform key), macro series, countries. Start here. |
| `get_company` | Profile and key metrics. |
| `get_financials` | Standardized IS/BS/CF, ratios and the segments & KPIs statement, up to 200 periods in one call — latest restated; `reporting_basis=as_reported` switches quarters to cumulative year-to-date. |
| `get_segment_revenue` | Latest revenue breakdown by business segment (or product, brand, channel) or by region, with its source filing or deck. |
| `get_fact_source` | The XBRL fact, filing accession and calculation tree behind one line — the citation tool. |
| `list_filings` | Filing index (per company, or market-wide latest). |
| `get_filing_sections` | Parsed sections (MD\&A, risk factors, …) with ids. |
| `get_section_text` | One section as plain text. |
| `get_events` | 8-K items per company, or the searchable market-wide wire. |
| `get_event_text` | One 8-K item's text; the item code is auto-resolved when unambiguous. |
| `get_news` | The intraday news tape (filings, wires, central banks, macro prints, halts) — market-wide with ticker/topic/flash filters, or one company's tape; every item carries its source attribution. |
| `list_transcripts` | Earnings-call transcript index. |
| `get_transcript` | Transcript text (latest call by default; the required date is resolved for you) or its extracted annotations. |
| `get_guidance` | Open management commitments + the resolved-guidance scorecard, merged. |
| `get_macro_series` | Country overview, or one point-in-time macro series. |
| `get_intelligence_graph` | The validated causal claim graph (optionally focused on a node). |
| `simulate_shock` | Shock propagation through the claim graph. |
Text tools (`get_transcript`, `get_event_text`, `get_section_text`) return plain text with a
`[Source: …]` citation line; everything else returns JSON identical to the corresponding REST
endpoint.
## Metering, auth and limits
* A tool call is metered like the REST request(s) it makes — the same per-minute and monthly
counters as the REST API. Most tools make one request; `get_transcript` (index + text) and
`get_guidance` (commitments + scorecard) make two, and `get_event_text` makes two when it
has to look the item code up first. Protocol plumbing (`initialize`, `tools/list`) is
free. MCP calls appear in the [usage dashboard](https://astreus.ai/developers)
as `/api/mcp#`.
* `get_financials` takes the same `period_type` (including `semiannual`), `reporting_basis`
and accounting `basis` as the REST route, and `get_company` returns the company's
`accounting_bases` so an assistant can ask for the right one.
* Two credentials work: **API keys** (`pk_live_...`, as a Bearer or `X-API-KEY` header) and
**OAuth tokens** from the connector flow. Both are data-scoped — key management, billing
and account routes reject them by design.
* When you're rate limited, the tool result says how many seconds to wait; assistants honour it.
## What the tools do not cover
The tool set is the read path an assistant needs most. Filing-note tables and series, the
as-filed statement view, investor presentations, ownership, people, prices, benchmarks and
correlation have no MCP tool today — the [data catalog](/data-catalog) has the full map.
Every one of them is a [CLI](/cli) command (`astreus note-tables`, `astreus note-series`,
`astreus as-filed`, `astreus presentations`, `astreus ownership`, …), and `astreus mcp` runs alongside
those commands, so an agent with the CLI installed reaches both.
## Rules the server enforces on itself
The server's own instructions carry the contract from
[agents.md](https://astreus.ai/agents.md): cite accession numbers next to
figures, respect vintages (`/financials` is latest-restated and names its filing; macro is
point-in-time), treat null as "not available" — never zero — and present data without
investment advice.