# @prereason/mcp
[](https://www.npmjs.com/package/@prereason/mcp)
[](https://www.npmjs.com/package/@prereason/mcp)
[](https://nodejs.org)
[](https://opensource.org/licenses/MIT)
[](https://glama.ai/mcp/servers/PreReason/mcp)
[](https://smithery.ai/servers/prereason/briefings)
**[Prereason](https://www.prereason.com) first. Then answer.**
Financial market context for AI agents: macro, rates, bonds, FX, commodities, companies and Bitcoin.
[Docs](https://www.prereason.com/docs#mcp-integration) · [Briefings](https://www.prereason.com/briefings) · [Company briefings](https://www.prereason.com/docs/company-briefings) · [Pricing](https://www.prereason.com/pricing) · [Get a key](https://www.prereason.com/signup)
Ask your AI where Treasury yields are. On its own, it reaches for a search result or a raw series and works out the rest by itself. When it prereasons, one `get_context` call brings back the context already worked out: the 30 year yield at 5.67% on 2026-10-07, the highest reading on the US Treasury's daily par yield curve since July 2001.
## Why prereason?
- **The analysis, and the data behind it.** Each briefing arrives with the reading done: the trend over several windows, where a value sits in its own history, a company's rank among its peers and, where read, its own guidance.
- **Every figure dated, every source named.** Your agent can say when a number is from and where it came from.
- **One call, a whole briefing.** A briefing gathers the series a question needs, so the turns go to the answer rather than to lookups.
- **The markets in one place.** Rates and Treasuries, the Fed, FX, commodities, macro, listed companies in the USA, Japan, Korea and India, and Bitcoin.
- **It describes; it never advises.** Briefings say what the data shows. They never say what to buy, sell or hold.
- **Quick to set up.** One block of config for Claude, Cursor, Codex or VS Code, through the npm bridge or the remote server. The catalogue tools need no key; for the rest, the bridge gives you one link to approve in your browser and the key arrives in the running session; the remote server takes your API key as a header.
## What it covers
PreReason gives an AI agent market context it can reason with. One call returns a briefing with the analysis already in it: a one line reading, trend direction over several windows, confidence scores, percentile ranks and correlations, and in the deeper briefings a regime label and a plain language narrative. The briefings cover macro, bonds, FX, commodities, Bitcoin, Ethereum and cross asset correlations. Company briefings cover listed companies in the USA, Japan, Korea, India, the UK, France, Austria, Belgium, Denmark, Finland, Iceland, Italy, Lithuania, the Netherlands, Slovenia and Slovakia, one company per call. The catalogue holds 33 live briefings and 293 individual metrics, among them Treasury yields, the latest FOMC statement, the macro release calendar, Treasury auctions, who holds US Treasuries, the Fed balance sheet, M2, net liquidity, the dollar, US crude and gas inventories, gold, silver, copper and wheat, oil, mining and agribusiness companies beside their commodity, AI compute and power demand, Bitcoin price and momentum, Bitcoin network and miner health, spot Bitcoin ETF flows and corporate Bitcoin treasuries. It is served over MCP (a remote server and an npm bridge) and over REST, as Markdown or JSON. Over MCP, the catalogue tools need no account, and a briefing needs a PreReason account, signed in through the connector or with an API key; a free account reads the free briefings. Over REST, a briefing takes an API key or, on the routes that take one, an x402 payment per call with no account.
## Quick Start
### Option 1: Claude Desktop, no key needed
**Requires [Node.js 18+](https://nodejs.org), and nothing else: the bridge has no dependencies.**
Add this to `claude_desktop_config.json` and restart Claude Desktop:
```json
{
"mcpServers": {
"prereason": {
"command": "npx",
"args": ["-y", "@prereason/mcp"],
"env": { "PREREASON_CLIENT": "claude-desktop" }
}
}
}
```
The catalogue tools work at once. To connect your account, tell Claude "connect me to PreReason", or ask for any briefing: either way Claude shows one link, `https://www.prereason.com/claim/PR-XXXX-XXXX`. Open it, sign in or create a free account, click Approve. The key arrives in the bridge on its own, is saved to `~/.prereason/credentials.json`, and is never shown; ask Claude whether PreReason is connected and it names your plan. Nothing is created in your account until you click Approve, and the link is asked for when you need it, so it never runs out while Claude sits open. If your account already holds as many API keys as it allows, the answer says so instead of looping: revoke a key under Settings on prereason.com, then ask to connect again, or set `PREREASON_API_KEY` to a key you already have.
Config file location:
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux:** `~/.config/Claude/claude_desktop_config.json`
Already have a key? Add it to the `env` block as `"PREREASON_API_KEY": "pr_live_..."` and the bridge never asks.
### Option 2: Direct HTTP with an API key (Claude Code, Cursor, Windsurf, Codex, Gemini CLI, VS Code, scripts)
Clients that hold their own config can call the endpoint directly, with the key as a header:
```bash
# Claude Code
claude mcp add --transport http prereason https://api.prereason.com/api/mcp --header "Authorization: Bearer YOUR_API_KEY"
```
```json
{
"mcpServers": {
"prereason": {
"type": "http",
"url": "https://api.prereason.com/api/mcp",
"headers": { "Authorization": "Bearer YOUR_API_KEY" }
}
}
}
```
Windsurf uses `serverUrl` instead of `url`; Gemini CLI uses `httpUrl`; Codex uses `url` plus `bearer_token_env_var` in `config.toml`. No key yet? Point the client at the endpoint without a header to browse the catalogue, then create a key on the website (below) and add the header.
### Option 3: Claude.ai and Claude Desktop custom connector
[Add PreReason as a custom connector](https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=PreReason&connectorUrl=https%3A%2F%2Fapi.prereason.com%2Fapi%2Fmcp), choose "No sign-in", and where the Request headers section is available add `Authorization` with the value `Bearer YOUR_API_KEY` (the word Bearer and the space are part of the value). Sign in support for connectors is being re-tested and is not offered until it is verified.
## Get an API Key
Three ways, all free. The hosted server never hands out a key inside a session and never asks for one.
**Through this bridge.** Run it with no key set: when you ask your assistant to connect PreReason, or an answer needs a key, it asks PreReason for access on your behalf and shows one `approve_url`, in its log and in the answer. Open it, sign in or create your account, click Approve, and the bridge saves the key, attached to your account and named `Agent: 
- **Name the company** with `entity`: a USA ticker or CIK (`NVDA`), a Japanese securities code (`7203`), a Korean stock code (`005930`), an Indian company's ISIN (`INE018A01030`) or the LEI of a company filing in the UK or of a European company (`2138002P5RNKC5W2JZ46`).
- **Not sure of the code?** Call `list_briefings` with `search`, for example `"Toyota earnings"`: the answer lists the matching covered companies, each with the `entity` to pass.
- **Read one part** with `block`, one of the 11 below, or leave it out for the whole briefing. A part counts one call; the whole briefing counts one for each part it carries. Parts are served for today only.
```
get_context(briefing="equities.company", entity="7203")
get_context(briefing="equities.company", entity="NVDA", block="valuation")
```
| Part (`block`) | What it holds |
|----------------|---------------|
| `header` | Who the company is, the indexes that hold it with their dates, and a line on its peers |
| `what_changed` | Its recent filings |
| `situations` | Flagged conditions, each with its severity |
| `against_guidance` | The company's own stated expectations next to what it reported (USA companies only) |
| `numbers` | Income statement, balance sheet and cash flow history, with growth and the company's own history |
| `segments` | Business, product and geography splits (USA and Japan) |
| `valuation` | The close, market capitalisation, price to earnings, book and sales, enterprise value multiples and free cash flow yield, each with its value a year ago and its own history (closes from StockAnalysis.com) |
| `capital_structure` | Debt, liquidity and maturities |
| `quality` | Earnings quality and liquidity, including the accrual ratio, cash conversion, current, quick and cash ratios, working capital, asset turnover, and days sales, inventory and payables outstanding |
| `profitability` | Returns and cash generation, including free cash flow, its margin and per share, EBITDA, return on equity, assets and invested capital, the payout ratio and the effective tax rate |
| `news` | Filed news |
## Example Prompts
Once connected, try prompts like:
- "Connect me to PreReason"
- "Show me the macro snapshot"
- "Where are Treasury yields, and what did the Fed last decide?"
- "What did NVIDIA report, and how does it rank among its peers?"
- "How is Bitcoin moving with stocks and the dollar?"
- "List available briefings"
## Troubleshooting
### "Server disconnected" error
- Ensure Node.js 18+ is installed: `node --version`
- Check your API key starts with `pr_live_`
- Fully quit Claude Desktop (system tray > Quit) and reopen
### Tools not appearing
- Restart Claude Desktop after editing config
- Verify JSON syntax: `node -e "JSON.parse(require('fs').readFileSync('path/to/config','utf8'))"`
### Windows: "'C:\Program' is not recognized"
If you still see this error, ensure you're using the `env` block (not `--header` args) as shown in Quick Start above. If the issue persists, install globally and use `node`:
1. Run: `npm install -g @prereason/mcp`
2. Use this config (replace `YOUR_USER` with your Windows username):
```json
{
"mcpServers": {
"prereason": {
"command": "node",
"args": [
"C:\\Users\\YOUR_USER\\AppData\\Roaming\\npm\\node_modules\\@prereason\\mcp\\bin\\cli.js"
],
"env": {
"PREREASON_API_KEY": "YOUR_API_KEY"
}
}
}
}
```
### Auth errors on get_context / get_metric
- `list_briefings`, `list_metrics`, and `get_health` work without a key
- `get_context` and `get_metric` require a valid API key, and `get_changes` a key on the Basic or Pro plan
- Get a free key at [prereason.com/signup](https://www.prereason.com/signup)
## Other MCP Clients
If your client supports remote HTTP servers, use [Quick Start Option 2](#option-2-direct-http-with-an-api-key-claude-code-cursor-windsurf-codex-gemini-cli-vs-code-scripts) above. The stdio bridge package is only needed for clients that require stdio transport (e.g. Claude Desktop).
## CLI Usage
```bash
# No key: the bridge asks for access and prints one link to approve
npx @prereason/mcp
# Ask for access now, save the key, exit (useful before a first run)
npx @prereason/mcp --login
# Forget the saved key
npx @prereason/mcp --logout
# Use a key from the environment (never asks)
PREREASON_API_KEY=pr_live_... npx @prereason/mcp
# Name the app the bridge runs in, so your dashboard names the connection
PREREASON_CLIENT=claude-desktop npx @prereason/mcp
# --header (backward compatible), a custom credentials file, a custom endpoint
npx @prereason/mcp --header "Authorization:Bearer YOUR_API_KEY"
npx @prereason/mcp --credentials-file /path/to/credentials.json
PREREASON_URL=https://custom.endpoint/mcp npx @prereason/mcp
npx @prereason/mcp --help
```
Key precedence: `PREREASON_API_KEY`, then `--header`, then the credentials file (`~/.prereason/credentials.json`, or `PREREASON_CREDENTIALS_FILE`, or `--credentials-file`), then the claim flow. The file holds the key and which claim issued it, never a claim token. On macOS and Linux the directory is created 0700 and the file 0600; Windows has no mode bits, so the file relies on your profile directory's permissions like every other credential store there.
## Claude Desktop extension (.mcpb)
`mcpb/manifest.json` describes the same bridge as a single click Claude Desktop extension, key optional. To build the bundle: `npm install --omit=dev`, then `npx @anthropic-ai/mcpb pack .` from the package directory, and install the resulting `.mcpb` by double clicking it. Submission to the Claude directory goes through the desktop extension form and is a publisher decision.
## No dependencies
The bridge ships its own transports and installs nothing. `npm ls` on it is one line, `npx @prereason/mcp` fetches one 23 KB tarball and starts, and the code a security review has to read is the code in this repository.
It used to depend on `@modelcontextprotocol/sdk` for two classes, a stdio transport and a Streamable HTTP client. That pulled in 91 packages and 25 MB on disk, nearly all of it the SDK server half: Express, Hono, CORS, a rate limiter, an OAuth client and a schema validator, none of which a relay ever calls. `lib/stdio.js` and `lib/streamable-http.js` replace the two classes the bridge used, keep their framing and their callbacks, and are covered by the suite under `test/`.
## Links
- [Documentation](https://www.prereason.com/docs#mcp-integration)
- [Sign Up](https://www.prereason.com/signup)
- [API Discovery](https://www.prereason.com/.well-known/mcp/server.json)
- [Terms of Service](https://www.prereason.com/terms)
- [Privacy Policy](https://www.prereason.com/privacy)
## Privacy Policy
See [prereason.com/privacy](https://www.prereason.com/privacy) for data handling practices.
## License
MIT