Oxford Ledge MCP Server

Last updated: 2026-09-26 Version: 3.8.0 (gov-public-data-only surface; CUSIP + third-party-FRED carve-outs)

Ask your assistant; it reads the public record. This package lets Claude, Codex, Cursor or any client that speaks the Model Context Protocol 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.

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.0. 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 (the previous cut). Its changes from 3.7.0 are in 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 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 bond lookups are no longer in the package — use the hosted Oxford Ledge MCP server for those.)

Upgrading from 1.x / 2.0.0 / 2.0.1? See MIGRATING.md (GitHub — this file and CHANGELOG.md are not in the wheel or the sdist). Short version: tool names, arg schemas, and config are unchanged across the 2.x series. Two substantive changes:

1. 2.0 extracted the shared tool registry into an oxford_ledge_mcp_core subpackage consumed by both the pip-installable server and Oxford Ledge's in-tree server. No user-visible behavior change.
2. 2.0.1 removed yfinance from this package (it was a ToS-violating scraper dependency). 11 tools that used to work standalone now require OXFORD_LEDGE_URL.
3. 2.0.2 internal-refactor cleanup; no behavior change.

---

Install

pip install oxford-ledge-mcp

The base install has zero third-party dependencies (stdlib only, since the 2.0.1 yfinance excision). The server ships with a built-in JSON-RPC-over-stdio fallback, so it runs as-is. For the canonical mcp protocol library path, install the optional extra:

pip install "oxford-ledge-mcp[mcp]"

If the mcp package is present the server uses it; otherwise it transparently falls back to the built-in stdio loop. Either way, requires Python ≥ 3.9.

The two transports agree. The 3.4.0 publish vet drove both and found them disagreeing on three things a client keys on; all three are closed in 3.4.0. On both transports in 3.4.0: a tool error (AUTH_REQUIRED, INVALID_PARAMS, DATA_UNAVAILABLE, RATE_LIMITED, an unknown tool) comes back flagged isError: true, so an agent framework that retries or aborts on the flag sees the same thing either way; a call missing a required argument is refused as INVALID_PARAMS naming the argument, and so is a number outside its declared minimum / maximum (see Argument bounds below — nothing is clamped on either transport); and tools/list carries the derived [Tier: free|plus] prefix on every description. How to pick: the built-in loop when you want zero dependencies (this is what a bare pip install or plain uvx runs); the [mcp] extra when your client or framework wants the reference protocol library's own framing and schema validation. Neither serves different data.

Running via uvx (no install). You can skip pip install and let uv fetch + run the package on demand — set "command": "uvx", "args": ["oxford-ledge-mcp"]. Because the package declares no required deps, plain uvx oxford-ledge-mcp runs the built-in JSON-RPC loop (complete, zero extra deps); add the official library with "args": ["--with", "mcp", "oxford-ledge-mcp"] only if you specifically want its protocol handling. Both connect to Claude Desktop. On Windows, if Claude Desktop reports the server failed to start, it usually can't find uvx on the GUI's PATH — use the absolute path as the command (e.g. C:\\Users\\<you>\\.local\\bin\\uvx.exe).

---

Three modes

This server runs in one of three modes — pick the one that matches your Oxford Ledge subscription state. The pip package is the user-distributed canonical path; the in-tree dev server is for Oxford Ledge contributors only.

1. API mode (recommended) — all 29 tools

For full functionality, point the server at a running Oxford Ledge instance. Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "oxford-ledge": {
      "command": "oxford-ledge-mcp",
      "env": {
        "OXFORD_LEDGE_URL": "https://www.oxfordledge.com",
        "OXFORD_LEDGE_API_KEY": "ol_live_..."
      }
    }
  }
}

OXFORD_LEDGE_URL should be the URL of an Oxford Ledge instance you have access to (the public app, your own self-hosted deploy, or http://localhost:5000 for local dev). If OXFORD_LEDGE_API_KEY is also set, a plain http:// URL is refused unless the host is a loopback address (127.0.0.1, 127.x.y.z, [::1]) or literally localhost -- the key would otherwise travel in the clear. Note that the 127.1 shorthand is not a parseable address and is refused; write 127.0.0.1. A key-carrying request to a loopback host is opened without any http_proxy / HTTP_PROXY from the environment -- it reaches the local interface directly, so a corporate or system proxy neither sees the key nor needs a no_proxy entry for this setup. Requests to an https:// host still honour the environment proxy.

OXFORD_LEDGE_API_KEY is your Oxford Ledge API key — create one in the app under YOUR API KEYS → + Create Key: sign in, then press K or click the key icon in the bottom bar, or open oxfordledge.com/?panel=api-keys, which opens the panel directly (there is no /account page). It is sent as the x-api-key header (never in a URL, a log line or an error message, and never forwarded across a redirect) and it is what makes the tools yours:

• Without it, this client is anonymous against the API — and 27 of the 29 tools still answer, deliberately: the 4 standalone tools never touch Oxford Ledge, the 14 name-proxied ol_* / gov tools ride the hosted server's anonymous /mcp transport, and the 9 REST-proxied tools call routes that carry no auth. What you do NOT get without a key: the two Plus-tier tools are refused as a free-tier caller — the hosted server's tier gate answers, and the wheel translates it to AUTH_REQUIRED saying which tier the tool needs, that this client is anonymous, that the operator sets OXFORD_LEDGE_API_KEY if they already have a plan that includes it (a paying subscriber who has not set the key gets exactly this refusal), and where to upgrade otherwise; and reads that only a keyed caller may trigger serve stored rows (the EDGAR refresh behind get_activist_stakes, which then reports stale: true).
• With it, tools resolve against your plan's tier, and calls are attributed to your account (see /api/billing/agent-usage). A valid key on a plan below Plus gets AUTH_REQUIRED too, but the sentence then says the key was accepted and the plan is what is missing — never "check the key". A trial key (ol_trial_...) works too — it lets you evaluate the paid tools for 14 days, no card, under a daily cap. With the key set, the nine REST-proxied tools also send one X-OL-MCP-Tool header whose value is the tool's own name (no arguments, no package version), so those lookups count on your own activity page; it is never sent without the key and, like the key, never forwarded across a redirect.

What "FREE" means in a tool description. No plan tier is required — there is no paywall on the hosted channel for that tool, keyed or keyless. It does not mean unmetered: keyed calls (trial keys aside) count toward your account's agent-API allowance like every other keyed call. Keyless calls are not metered against any account.

Argument bounds. Every argument that declares a schema minimum / maximum (limit, days, since_days, quarters, max_holdings) or maxItems (ol_bdc_common_borrowers.bdc_tickers, 25) is validated before the call, on both transports: an out-of-range number is refused as INVALID_PARAMS naming the argument and the bound (`limit`: 5000 is greater than the maximum of 100 — the reference library's own sentence), an over-long list as `bdc_tickers`: [...] is too long, nothing is sent, and nothing is silently clamped or truncated. The hosted server refuses the same numeric bounds the same way (its own handler would slice a 26-ticker list at 25, which the wheel's schema declares instead of discovering). _meta.params_accepted echoes the arguments the host received; the completeness block on the payload reports what was actually served (complete: null at exactly the cap means undecidable — read more_available_hint). This is said once here rather than in every description.

2. Standalone mode — 4 tools, no Oxford Ledge account needed

A small subset of tools works without an Oxford Ledge instance — the ones backed by direct public APIs:

{
  "mcpServers": {
    "oxford-ledge": {
      "command": "oxford-ledge-mcp",
      "env": {
        "FRED_API_KEY": "your-fred-key"
      }
    }
  }
}

The four standalone tools split by their data source:

• 2 fully keyless — get_fundamentals + get_sec_filings (direct SEC EDGAR). No env var of any kind.
• 2 require FRED_API_KEY — get_yield_curve and get_fred_data call FRED directly and raise ToolError.API_REQUIRED with a "Set FRED_API_KEY" message if the key is unset. Get a free key at fred.stlouisfed.org. (get_fred_data serves U.S.-government / public-domain series only; third-party-copyright series — S&P, ICE BofA, Moody's, CBOE, University of Michigan — are refused.)

The other 25 tools raise ToolError.API_REQUIRED with a pointer to set OXFORD_LEDGE_URL when called in standalone mode. This is a change from 1.x / 2.0.0, which used yfinance to cover more standalone tools. That path was removed in 2.0.1 — see MIGRATING.md for the rationale.

3. Dev mode — in-tree from an Oxford Ledge checkout

If you're an Oxford Ledge contributor working on the parser/dispatcher itself, run mcp_server.py directly from your checkout:

{
  "mcpServers": {
    "oxford-ledge-dev": {
      "command": "python",
      "args": ["/abs/path/to/oxford_ledge/mcp_server.py"],
      "env": {
        "OXFORD_LEDGE_USER_TIER": "pro"
      }
    }
  }
}

OXFORD_LEDGE_USER_TIER is enforced in dev-mode by the in-tree server (M2 tier-gate, 2026-04-24); set it to one of the real tier keys — free, plus, pro, professional, institutional_plus, team, or team-member (the ranking lives in oxford_ledge_mcp_core/registry.py::TIER_RANK) — to test tier-restricted tools. The old display-name spellings learner and analyst are NOT tiers: learner aliases to free (denied for gated tools) and analyst is deliberately unaliased (denied). Not used in API or standalone modes: API mode authenticates with your OXFORD_LEDGE_API_KEY (the hosted remote endpoint is key/Bearer-only — session cookies are deliberately not accepted there); standalone mode has no tiers at all.

After editing config, restart Claude Desktop. You'll see the tools available.

---

Available tools (29)

Mode column: S = works in standalone (no OXFORD_LEDGE_URL required), A = API mode only (needs OXFORD_LEDGE_URL; a key only for the two marked Plus). As of 3.1.0 28 of the 29 tools are gov-public-data (SEC EDGAR / FRED / Treasury / FDIC / USAspending / USPTO / CFTC) and the 29th, get_value_investing_fact, is Oxford Ledge-authored, with third-party-copyright fields excluded — CUSIPs (FactSet IP) are stripped from 13F/event payloads, and S&P/ICE/Moody's/CBOE FRED series are refused. Each tool's description (what tools/list returns) is the contract: it states units, the row shape, what an empty result means, and which fields are Oxford Ledge derivations rather than the source's own figures.

Removed — vendor / third-party-copyright lineage (pin an older version if you need them): 3.1.0 (CUSIP + FINRA-attribution carve-out): search_bonds, get_bond_data (bond CUSIPs are FactSet IP), get_short_interest (advertised stub, unresolved float-lineage + FINRA-attribution) — pin ==3.0.1. A ==3.0.1 pin does NOT bring the two bond tools back as working tools: FINRA auth-walled the public TRACE hosts they scraped in 2026-07, and on 2026-09-13 both were RETIRED on the hosted server as well (the hosted names answer status: "retired" with empty lists / null prices, never data). For corporate-bond discovery use the hosted server's ol_bond_directory_screen (LQD/HYG directory — reference data, no prices); for one issuer's own maturity schedule, get_debt_maturities in this package. 3.0.0 (keyless-public cut): get_stock_quote, get_financials, get_balance_sheet, get_cash_flow, get_analyst_recommendations, get_company_info, compare_stocks, screen_stocks, get_anomaly_flags, get_options_chain, get_economic_calendar, get_news, search_company (pin ==2.1.0). 2.1.0 (FMP-removal): get_company_data, get_company_profile, get_market_indicators, get_valuation_history, calculate_intrinsic_value, get_price_history, get_peer_comparison (pin ==2.0.4). These remain available via the hosted Oxford Ledge MCP server. See CHANGELOG.md / MIGRATING.md.

SEC fundamentals & filings (4 tools)

Tool	Mode	Description
get_fundamentals	S	Up to 10 years of XBRL financials from SEC EDGAR companyfacts (LongTermDebt, not total debt; per-period concepts; NCI-aware equity rung; Oxford Ledge split-basis check on EPS / diluted shares incl. steps across tagging holes; coverage[].contiguous)
get_sec_filings	S	The 10 newest EDGAR submissions of any form (filing_type narrows), with form, date, link and a window disclosure
get_capital_allocation	A · Plus	Capital-allocation scorecard from SEC XBRL — up to 30 fiscal-year labels with periods and a split-basis basis block, a 10-year summary window; dividends, net buybacks (issuance, IPO proceeds and SBC netted), net debt change, acquisitions, shares outstanding (hosted tool, name-proxied; the net series are Oxford Ledge derivations)
get_debt_maturities	A · Plus	Forward maturity ladder from 10-K/20-F footnotes, in millions of USD, with parser confidence + balance-sheet validation (hosted tool, name-proxied; EDGAR only)

Ownership & insiders — SEC (6 tools)