oxford-ledge-mcp

# Oxford Ledge MCP Server

> **Last updated:** 2026-09-27
> **Version:** 3.8.1 (gov-public-data-only surface; CUSIP + third-party-FRED carve-outs)

<!-- mcp-name: com.oxfordledge/oxford-ledge -->

Ask your assistant; it reads the public record. This package lets Claude, Codex, Cursor or any client that speaks the [Model Context Protocol](https://modelcontextprotocol.io/) look things up in SEC filings and fundamentals, 13F holdings, insider trades, BDC loan books, and Treasury, FRED, FDIC, USAspending, USPTO and CFTC data, with the source named on the answer.

**Install:** `pip install oxford-ledge-mcp` (Python 3.9 or later, no third-party dependencies). **Connect:** step-by-step setup for each client, and a free API key, at **[oxfordledge.com/mcp](https://www.oxfordledge.com/mcp)**. **Registry:** listed in the official [MCP Registry](https://registry.modelcontextprotocol.io/) as `com.oxfordledge/oxford-ledge`, with this package and, as its remote, the hosted server at `https://www.oxfordledge.com/mcp`.

Free on every Oxford Ledge plan, and a few tools run with no account at all (see *Standalone mode* below). The release notes come next; what the tools cover, the three modes, the tool list and the data terms follow them.

## Release notes

**This is 3.8.1.** A patch release on 3.8.0: no tool, argument or data key is added, renamed or removed. **Changed:** every request this package sends to Oxford Ledge -- the REST proxy calls and both hosted-tool legs, with or without a key -- now names the package version in its User-Agent, `OxfordLedgeMCP/1.0 (oxford-ledge-mcp 3.8.1)` instead of the constant `OxfordLedgeMCP/1.0`, so a report about a call can be matched to the release that made it; the requests it sends to SEC EDGAR and FRED are unchanged. **Changed:** `get_corporate_events` carries one more entry in its `tool_notes`: an empty (or null) `description` is a filing whose text has not been read yet (not fetched, or it could not be extracted), never a filing that says nothing -- open `sourceUrl` to read it. **Docs:** this README now notes the official MCP Registry listing (above).

**3.8.0 (the previous cut).** It also carries everything in the 3.7.2 cut described next, which was never published on its own -- upgrading from 3.7.1 gets both. **Changed:** every tool description is now a short card of at most 1,300 characters -- what the tool returns, its key arguments, its source and the one caveat to know before calling -- so a connected session spends far fewer tokens before its first call (the 29 descriptions went from about 70,900 to about 23,700 characters). The caveats that used to live in the descriptions now ride each response in a `tool_notes` list, placed near the head of the payload; licence, redistribution and refusal notices stay verbatim in the descriptions. **Changed:** `response_size.over_budget` now judges the data without `tool_notes`, while `chars` still reports the whole payload. No tool, argument or data key is renamed or removed.

**3.7.2 (folded into 3.8.0, never published separately).** The changes below landed between 3.7.1 and the 3.8.0 description change. **Removed:** `amount` and `status` on `get_corporate_events` -- no writer ever filled them, so they were always null. **New keys this package passes:** `filedName` on `get_13f_holdings` (the issuer name exactly as filed, present only when the served `name` differs); on `get_holders`, `shares_outstanding_period` (the fiscal period of the share count ownership percentages divide by) and `other_class_rows_excluded` (rows filed under another share class of the same company, left out of the totals); `priceApplicable` on `get_insider_trades` rows (false for gifts, awards and other codes filed at a price of 0 -- the filed 0 is kept); `grossRepurchases` per year and `totalGrossRepurchases` on `get_capital_allocation` (null when untagged; `netBuybacks` is unchanged and is a dilution proxy); `last_ingested_at` and `parent_patent_number` on `ol_patents`; `fred_notice` on `get_fred_data` and `get_yield_curve` (the FRED terms-of-use sentence). **New arguments:** `limit` and `days` on `get_insider_trades`; `common_only` (default true) and `min_value` on `ol_insider_recent_buys`. **Host-side changes (an installed 3.7.1 sees them too):** Class A and Class B holdings are no longer mixed (Berkshire Hathaway Class A positions had been served as Class B holders); `get_corporate_events` fills `counterparty` from the M&A reader when its confidence is at least 0.5 (labelled derived). **BDC (MCP-D):** `ol_bdc_borrower_dispersion` now returns one row per LENDER (`limit` counts lenders; the tranches are nested under `tranches`; new `lender_count`, `tranche_count`, `lender_row_basis`, `par_amount`, `cost_amount`; stale lenders are left out unless `include_stale` is true, reported as `stale_lenders_excluded`; `count` now counts lenders), and a row whose par mark sits well below its cost mark on a loan otherwise marked near cost carries `mark_basis` / `mark_basis_note` (a partly funded commitment) and no yield; `get_bdc_holdings`' `parseQuality` is `suspect` whenever the book's fair value is refused. **Borrower descriptions:** research-written descriptions are labelled as written by an AI model from public web sources and not checked for copying; descriptions whose research cited paywalled or restricted databases are no longer served (`descriptionWithheld` says why), and `descriptionSources` appears where the source was recorded.

**3.7.1.** Its changes from 3.7.0 are in [MIGRATING.md](https://github.com/hs902/oxford-ledge-mcp/blob/main/MIGRATING.md). No tool, argument or key is renamed or removed, no argument changes, and nothing new is sent. **Six keys the Oxford Ledge server already sends now pass this package's fail-closed emit filter** (3.7.0 stripped them): `fairValueGap` / `fairValueGapNote` on `get_bdc_list` and `get_bdc_holdings` -- the label and sentence that say when a BDC's parsed-row total disagrees with the filing's own total by more than 5%, including the under-count case where `totalFairValue` understates the book; `withheld` / `parser_dialect_version` on `ol_bdc_credit_quality` -- why a covered non-accrual rate is null (`coverage_state` `implausible`: more than 25% of the determinate debt book flagged AND the flagged loans marked near par, a sign Oxford Ledge's parse misread the schedule; a rate above 25% on loans marked below 85, or with no mark on file to test, is stated as `unusually_high` -- check the filing) and which parser generation read the quarter; `verbatim` on `get_value_investing_fact`; and `issuerSelfFiled` on `get_insider_trades` and `ol_insider_recent_buys` -- true when the Form 4 was filed under the company's own SEC ID, so the reporting-owner field names the company, not a person (3.7.0 served those same rows unlabelled; Oxford Ledge never counts them in its own totals, and neither should yours). On `get_insider_trades` the key is absent, never `false`, when the host that answered does not send it. **Descriptions corrected to the wire:** a `get_value_investing_fact` entry paraphrases or summarises the named author's ideas in wording not verified against the source (some entries may repeat the author's own words), so it is not a verbatim quotation unless `verbatim` is true -- `attribution` is the credit line to use; `ol_bdc_top_borrowers` ranks on the ACTIVE lender count; `ol_bdc_mark_changes` names its `fair_value_refused` exclusion. **Host-side changes the descriptions now state** (an installed 3.7.0 sees them too, under keys it already passes): `reportedTotalFairValue` is null, never 0, when the filing tags no usable total or when Oxford Ledge's stored reference describes a different filing than the book served; `get_bdc_list`'s `lastParsed` is the date Oxford Ledge last wrote the BDC's registry row; MRCC (merged into HRZN) has left `get_bdc_list`; and `ol_bdc_mark_changes`' `filters.debt_mark_band_pts` is now [30, 105]. The 3.7.0 changes (the `X-OL-MCP-Tool` header, `get_bdc_holdings` paging, `get_fails_to_deliver`'s `end_date`, `_meta.response_size`, the `MORTGAGE30US` / `AAA` refusal) are under their own heading there.

## What the tools cover

**29 tools** for SEC filings & fundamentals, institutional & insider ownership, BDC/private-credit holdings, macro rates, and federal reference data (FDIC, USAspending, USPTO, CFTC). As of 3.1.0 this is a **gov-public-data-only** package: 28 of the 29 tools are backed by a **U.S.-government public source** — SEC EDGAR, FRED, U.S. Treasury, FDIC, USAspending, USPTO or CFTC — and the one exception, `get_value_investing_fact`, is Oxford Ledge-authored (`basis: ol-authored`, a curated corpus of attributed paraphrases and principles whose wording is not verified against the primary source -- `author` / `source` / `attribution` on every row, and `verbatim` is true only for a text verified against its primary source); there is no commercial-vendor feed anywhere in the surface, and third-party-copyright data is excluded (S&P/ICE/Moody's/CBOE FRED series are refused; FactSet-licensed bond CUSIPs are not disseminated). The software is MIT-licensed and Oxford-Ledge-authored; the **data** it returns carries its own terms (see [Data license](#data-license) below). **27 of the 29 tools are reachable with no Oxford Ledge account:** 4 run fully standalone against public APIs (2 SEC EDGAR, keyless; 2 FRED, needing a free `FRED_API_KEY`), and 23 more answer keyless once `OXFORD_LEDGE_URL` points at a running Oxford Ledge instance (14 name-proxies of the hosted MCP's anonymous `/mcp` transport plus 9 proxies of unauthenticated REST routes). Only the two Plus-tier tools (`get_debt_maturities`, `get_capital_allocation`) need an `OXFORD_LEDGE_API_KEY`. API mode **with** a key is still the recommended install: it attributes calls to your account, unlocks the two paid tools, and is the only leg that can refresh a stale EDGAR cache (see `get_activist_stakes`). (Vendor-fed quotes/estimates/screens/news and CUSIP