{
  "markdown": "# EdgeDepth Research MCP Server\n\n`@edgedepth/research-mcp` is the official, research-only Model Context Protocol server for [EdgeDepth](https://edgedepth.com/), a [market microstructure search engine](https://edgedepth.com/research) over recorded Binance USDT-M crypto and TradFi perpetuals. Use it from ChatGPT, Claude, Cursor, Codex, or any MCP client to find every verified occurrence of a market condition, inspect forward outcomes across the complete matched set, read an unconditional same-scope reference, and open replay-linked evidence.\n\nEvery result includes counts with denominators and a reproducibility key. Same key, same bytes.\n\n[Website](https://edgedepth.com/) · [Search the market](https://edgedepth.com/research/workbench) · [REST API documentation](https://app.edgedepth.com/research/api) · [MCP setup guide](https://app.edgedepth.com/research/api/mcp) · [Learning hub](https://edgedepth.com/learn/)\n\n## Why use EdgeDepth Research?\n\n- **Search recorded market microstructure:** query a closed, versioned feature registry covering order flow, price action, volatility, funding, open interest, positioning, candle formations, and liquidations.\n- **Keep the denominator:** every count reports the eligible population and exclusions behind it. Missing data is absent, never silently changed to zero.\n- **Measure outcomes without lookahead selection:** forward returns, MFE, and MAE are computed over all occurrences. Outcome fields cannot be used as filters.\n- **Compare matched and baseline populations:** deterministic cohort results put the matched distribution beside every other eligible predicate-false bucket.\n- **Audit and replay the evidence:** results carry a reproducibility key, and representative occurrences include authenticated web handoffs to the exact recorded market moment.\n- **Stay research-only:** no tool trades, modifies alerts, publishes reports, or writes account data. A fresh scan, cohort, or stratified computation can consume research allowance units; the annotations state that side effect explicitly.\n\n## Choose a connection\n\nThe package exposes one tool core through two transports:\n\n- **Hosted MCP (recommended):** connect to `https://mcp.edgedepth.com/mcp` over Streamable HTTP and authorize once in your browser. No API key to copy.\n- **Local stdio:** run `npx -y @edgedepth/research-mcp` with an EdgeDepth API key.\n\n## Connect\n\n### Claude Desktop\n\nIn **Settings > Connectors > Add custom connector**, enter:\n\n```text\nhttps://mcp.edgedepth.com/mcp\n```\n\nComplete the EdgeDepth browser authorization prompt.\n\n### Cursor (`~/.cursor/mcp.json`)\n\n```json\n{\n  \"mcpServers\": {\n    \"edgedepth-research\": {\n      \"url\": \"https://mcp.edgedepth.com/mcp\"\n    }\n  }\n}\n```\n\n### Codex (`~/.codex/config.toml`)\n\n```toml\n[mcp_servers.edgedepth]\nurl = \"https://mcp.edgedepth.com/mcp\"\n```\n\nThen run:\n\n```bash\ncodex mcp login edgedepth\n```\n\nRemove any old `bearer_token_env_var` line before using browser OAuth.\n\n### Local stdio with npx\n\nCreate a key on the [EdgeDepth Developer page](https://app.edgedepth.com/account/developer), then add:\n\n```json\n{\n  \"mcpServers\": {\n    \"edgedepth-research\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@edgedepth/research-mcp\"],\n      \"env\": {\n        \"EDGEDEPTH_API_KEY\": \"edk_live_YOUR_KEY\"\n      }\n    }\n  }\n}\n```\n\nLocal stdio requires Node.js 20 or newer. Use the `research:read` key scope for recorded-data tools and add `research:interpret` only when you need the free `interpret_prose` proposal step.\n\n## Result projection (agent context economy)\n\nScan-family results are large: a universe scan's canonical bytes run to\nhundreds of kilobytes, most of it page rows carrying every recorded feature,\nthe zero and long-tail entries of `counts_by_symbol`, and empty threshold\nrungs. That overflows a client's tool-result budget before it answers anything.\n\n`run_scan`, `next_page` and `run_cohort` therefore return a **stated\nprojection** by default. It only ever REMOVES, and every removal is listed in a\ntrailing note with the exact way to get the bytes back:\n\n- occurrence rows are trimmed to `rows` (default 3) and each kept row keeps the\n  setup fields its own `evidence` block names - `full_rows: true` restores the\n  whole vector;\n- the per-occurrence `outcomes` map keeps the entries for the rows that remain;\n- `counts_by_symbol` keeps the top entries by match count, and says how many\n  instruments and matches were omitted;\n- the outcome ladders are replaced by a paired answer block: for each metric,\n  `present`, `absent` and the selected rungs' integer counts pass through\n  verbatim, with `rate`, the unconditional `baseline_rate` over the same\n  symbols and window, and their ratio as `lift` stated beside them. The\n  selection is fixed in advance (`gte 0.01`, `gte 0.02`, `lte -0.01`,\n  `lte -0.02`), drops rungs that separate nothing, and adds the single rung\n  carrying the largest lift among those holding at least 30 occurrences,\n  marked `kept_for`. `full_outcomes: true` returns every rung and the per-rung\n  histogram, on the matched set and the reference separately.\n\nCounts, denominators, absent tallies, `predicate_coverage`, representatives,\nthe page cursor and the reproducibility key are never touched, and the request\ndocument is never rewritten, so the canonical query hash and the credit charged\nare exactly what you asked for. `full_counts: true` returns the engine's\nverbatim canonical bytes with no projection at all. ETags are\nprojection-scoped: an ETag held for one projection can never revalidate as a\ndifferent one.\n\n`list_features` takes the same treatment on request: `search`, `feature_ids`\nand `compact` return one feature family instead of the whole grammar, with the\nclosed parts (operators, windows, sequence rules, limits, error codes) intact.\n\n## Prompts and resources\n\nThe server publishes worked prompts, which compatible clients surface as\npickable commands: `test_a_claim`, `liquidation_cascade_bounce`,\n`investigate_symbol`, `what_preceded_moves_like_this`, `does_it_confirm` and `how_common_is_it` (the free\nprevalence path). Each one encodes the same answer contract: ground the\ngrammar, propose the exact definition, wait for confirmation, then report with\ndenominators, the reference, the reproducibility key and a replay handoff.\n\nThe grammar registry is also served as a resource, `edgedepth://research/grammar`,\nso a client can attach it once instead of calling `list_features` every session.\n\n## Recommended agent workflow\n\n1. For setup-first natural-language questions, call `interpret_prose` first with the user's question unchanged. The interpreter already uses the registry. Do not insert unstated thresholds, dates, markets or outcome definitions. Use `list_features` only when constructing or repairing a document. It is the live, closed grammar and prevents invented fields. Its result also carries the human reading page for any feature id: `https://edgedepth.com/research/readings/<id without the \"feature.\" prefix>`, so `feature.vpin` is explained at [edgedepth.com/research/readings/vpin](https://edgedepth.com/research/readings/vpin). Open it when a person needs to know what a reading measures before a threshold is chosen.\n2. Call `list_instruments` only when you need to check the manifest-derived universe, coverage, and provenance. Its result carries the human market page in the same way, `https://edgedepth.com/research/symbols/<symbol>`, for a market still being recorded; a delisted market in the universe has no page, so offer that link rather than promising it.\n3. Show one short proposal: condition, exact markets and dates/time zone, outcome definition and horizon, and metering. Interpretation is free; fresh computations can consume allowance. Label every unprovided value as a proposed assumption using chip provenance. Resolve unsupported fragments and ask only questions that materially change the study. Keep exact JSON and diagnostics inspectable in tool details, available on request.\n4. Wait for explicit human approval, then pass the same document to `run_scan`. Changes require a new proposal and confirmation. The exact-document API does not store a proposal ID or a human approval receipt; client consent is required, and a model-supplied flag is not proof. On the supporting web release (b68c744 or later), returned `rq` workbench links load editable proposals and wait for Run; navigation never authorizes computation.\n5. Answer the question first, preserving zero-match and inconclusive findings. Give matched/eligible counts, coverage exclusions, present/absent outcomes, both directions at the agreed horizon, and overlap/selection limitations. Read rates from `outcomes_summary`, which covers all occurrences. Page rows are examples, never the denominator. Each rung already carries its matched count and rate, the unconditional rate, and their ratio as `lift`: quote those, and quote the count beside the rate. No `lift` means no reference was available or the unconditional rate was zero; neither licenses estimating one.\n6. Read the appended unconditional same-scope reference when available. It is not matched, comparable, or a causal control.\n7. Return the full reproducibility key with the answer and one relevant next action: a returned replay, a changed assumption, or an existing report. Saving and alerts remain web actions. Each handoff states how far back it sits; replay reach is a per-account entitlement, so an old moment can be refused at the web surface even though the occurrence is real. Use `next_page` only with a cursor returned by the API.\n\nExample instruction for an MCP client:\n\n```text\nDid elevated VPIN and one-sided buying tend to precede a rise? Propose a precise\nstudy before running anything. Label any suggested thresholds, markets, dates\nand outcome definition so I can approve or change them.\n```\n\nThe user does not need tool names, feature IDs or JSON. The client translates the\nconfirmed proposal into the existing exact-document call.\n\n## Outcome-first and pointed-move workflow\n\nFor an outcome-first question, use `outcome_first` after agreeing the target and\nscope. Preserve touched-within (`reached`) versus close-at-end (`finished`),\ndirection, size and horizon. Do not pass the outcome to the setup interpreter or\nsubstitute the worked example. The target grammar is available at\n`edgedepth://research/outcome-first`.\n\nReport the population and both counted shares for each displayed reading. Help\nthe person choose one reading, retrieve its `setup_first_rerun` with `full_rows:\ntrue` on the unchanged request, and confirm that exact setup before `run_scan`.\nRead the original outcome target from the complete matched-set summary; request\n`full_outcomes` if the projection omitted its rung. An unavailable rung is stated,\nnever replaced by the default horizon. The two reads have different denominators.\nA same-period rerun remains exploratory; freeze the condition and use a separate\nperiod before claiming validation.\n\nA named moment can be inspected with `snapshot_at`; `commonality` compares multiple\nsupplied moments. The screenshot path below adds bounded explicit close-range investigation and the existing\ndetector geometry. Automatic move selection is not exposed through MCP. Historical marker browsing, named\nsector/volume-tier resolution, and an exact pre-run allowance quote are not MCP\ncapabilities yet. `list_instruments` supplies coverage and instrument provenance,\nnot sector membership. Use an exact supplied roster or propose a resolvable scope;\nnever invent group members or a numeric price. Replay handoffs open the web surface\nand remain subject to the person's coverage and entitlement.\n\n## Tools\n\n| Tool | What it does |\n| --- | --- |\n| `list_features` | Returns the closed grammar registry: feature ids, types, ranges, operators, windows, sequence rules, limits, and error codes. `search`, `feature_ids` and `compact` narrow it. |\n| `list_instruments` | Returns the research universe and coverage. The default is a compact summary; use `symbols: [...]` for selected full records or `full: true` for the verbatim canonical universe. |\n| `interpret_prose` | Turns prose into a proposed query document. It does not execute the query. Optional `time_zone` accepts an IANA time zone for calendar planning. |\n| `run_scan` | Executes a `research_query.v2` document and returns result bytes with counts, denominators, outcomes, the unconditional same-scope reference, and the reproducibility key. Projected by default (`rows`, `full_rows`, `full_counts`). |\n| `next_page` | Continues a prior scan with its opaque cursor. Never construct cursors manually. |\n| `ground_screenshots` | Resolves host-extracted screenshot coordinates against recorded candle closes and coverage, retaining uncertainty and deduplicating event views. Free. |\n| `investigate_move` | Reads the existing lead-up and optional recorded detector geometry for a grounded event, and optionally prepares exact unrun setup documents. Free read; historical entitlement applies. |\n| `snapshot_at` | Reads registry feature values, window aggregates, and fired rules as of a recorded moment. |\n| `base_rate` | Counts matches and eligible buckets for one clause over a window. |\n| `commonality` | Finds the deterministic intersection across multiple moments with selection-bias caveats included. |\n| `get_report` | Retrieves a published report by its 8-character canonical hash. |\n| `run_cohort` | Compares what followed every match with what followed every other eligible predicate-false bucket. |\n| `run_stratified` | Partitions one matched population at its existing anchors into split-true, split-false, and split-absent outcome summaries. |\n| `outcome_first` | Starts from the MOVE instead of the setup: names an outcome (size, direction, horizon) and reports what the record was doing at five fixed offsets before every realised move like it. Each row carries two counted shares, the share before these moves and the share across every eligible minute in the same scope, plus the setup-first rerun that re-tests it the other way round. A descriptive read, never a rule search: a row is not a rule, a candidate or a finding, and the row order is display order. A scope with too few realised moves is refused with its counts and four adjustments, and a refusal spends nothing. Projected by default (`rows`, `full_rows`). |\n\nNo tool can trade, change market state, publish, or modify account data. `run_scan`, `run_cohort`, `run_stratified` and `outcome_first` are annotated as metered computations because a fresh call can irreversibly consume an allowance unit. The other recorded-data tools are closed-world reads. `interpret_prose` is a free read that uses the configured external language interpreter.\n\n## Research contract\n\n- Validation failures pass through as `422 {\"errors\":[{\"code\":\"...\",\"message\":\"...\"}]}`.\n- Transport failures use the `{\"error\",\"code\"}` envelope.\n- Contract codes are machine-actionable. For errors such as `UNSUPPORTED_FEATURE` or `OUTCOME_IN_PREDICATE`, call `list_features`, repair the document, and retry.\n- Deterministic tools are exact-document, UTC-only tools. `interpret_prose` may use a time zone to plan dates, but `run_scan`, `run_cohort`, and `base_rate` never reinterpret calendar language.\n- Reruns and ETag `304 Not Modified` revalidations are free. `list_instruments` ETags are scoped to the requested summary, symbol projection, or full representation.\n- Interpretation is free and never debits the scan allowance. An unavailable scan allowance returns neutral `402 RESEARCH_ALLOWANCE_EXHAUSTED` metadata without a checkout link.\n\n## REST API and documentation\n\nThe MCP server is a thin, deterministic interface to the public EdgeDepth Research API:\n\n- [REST API quickstart](https://app.edgedepth.com/research/api)\n- [Authentication and API keys](https://app.edgedepth.com/research/api/auth)\n- [Credits, caching, and limits](https://app.edgedepth.com/research/api/credits)\n- [Versioned query grammar](https://app.edgedepth.com/research/api/grammar)\n- [Reproducibility contract](https://app.edgedepth.com/research/api/reproducibility)\n- [Worked API examples](https://app.edgedepth.com/research/api/examples)\n- [MCP connection guide](https://app.edgedepth.com/research/api/mcp)\n- [How EdgeDepth Research works](https://edgedepth.com/learn/how-research-works/)\n- [What you can ask](https://edgedepth.com/learn/what-you-can-ask/)\n\nThe default REST base used by the stdio package is `https://app.edgedepth.com/api/v1/research`.\n\n## Environment\n\n### Local stdio\n\n| Variable | Default | Purpose |\n| --- | --- | --- |\n| `EDGEDEPTH_API_KEY` | None | Required for stdio tool calls. |\n| `EDGEDEPTH_API_BASE` | `https://app.edgedepth.com/api/v1/research` | Optional REST API base override. |\n\n### Hosted server operators\n\n| Variable | Default | Purpose |\n| --- | --- | --- |\n| `EDGEDEPTH_OAUTH_EXCHANGE_URL` | `http://127.0.0.1:3002/api/mcp/oauth/exchange` | OAuth access-token exchange endpoint. |\n| `MCP_INTERNAL_SECRET` | None | Required internal assertion secret; must match the web app. |\n| `PORT` | `3003` | HTTP listen port. |\n| `HOST` | `127.0.0.1` | HTTP listen host. |\n\n## Authentication and security\n\nThe hosted server uses browser OAuth. It validates opaque access tokens, exchanges them for separate short-lived internal assertions, and never passes the OAuth access token to the REST API. The MCP server is stateless and stores no user credentials.\n\nCompatible clients rotate refresh tokens silently while the connection remains active. Review or revoke access at [EdgeDepth Connected Apps](https://app.edgedepth.com/account/mcp).\n\nAPI keys remain available for scripts, local stdio, and MCP clients without browser OAuth. Treat an `edk_live_...` key as a secret and never commit it to source control.\n\n## Develop\n\n```bash\nnpm install\nnpm run build\nnpm test\nnpm run typecheck\n```\n\nTypeScript builds to `dist/`. Example nginx locations, systemd hardening, and operator environment values live under `deploy/`. Production deployment and npm publishing remain operator actions.\n\n## Related projects\n\n- [edgedepth-terminal](https://github.com/edgedepthhq/edgedepth-terminal) (AGPL): the open-source C++/WASM orderflow terminal. Replay-linked evidence from research results opens the exact recorded market moment in it, and it self-hosts with one docker compose command.\n- [edgedepth-gateway](https://github.com/edgedepthhq/edgedepth-gateway) (MIT): a Go bridge from Binance's public streams to the terminal's wire format, for running the terminal on live data without an account.\n\n## License\n\nMIT\n\n\n### Inline scan evidence\n\nSupported MCP Apps hosts can display a comparison and recorded-distribution card\nfrom `run_scan`. The card receives only complete-result forward-return summaries,\ncoverage, exact query/key and metering in tool-result `_meta`. This data is hidden\nfrom the model in ChatGPT; the existing text projection is unchanged. No raw page\nobservations are used to make distributions, no fitted curves are invented, and\nno additional requests or allowance consumption occur when changing chart views.\nReference distributions are compared only when their bin edges align. Empty bins,\nopen tails, missing outcomes and zero/one-observation states remain visible.\nHorizon and move-size controls are display choices over already-computed outcomes,\nnot changes to the approved query. The card defaults to the labelled 1h / 1% view.\nExact study/evidence details expand inside the card; text-only hosts keep the\nexisting response. The HTML resource has no network dependencies or mutations.\nThis is a developer-connector update, not an automatic official V1 rescan.\n\n\n## Screenshot-led investigation (local implementation; release required)\n\nAttach charts to a vision-capable host and use `investigate_screenshots`. The host\nreads the images; the server receives `screenshot_observation.v1` facts through\n`ground_screenshots`. The contract is `edgedepth://research/screenshots`. No second\nimage model or automatic attachment access is used.\n\nGrounding is free for every authenticated tier. It checks explicit minute-close\nboundaries against recorded Binance futures candles and manifest bounds, retains\nvisible/inferred/user/missing provenance, and deduplicates exact event views.\nUnclear dates, zones, inferred boundaries, conflicting coordinates and overlapping\nexamples need one clarification. No default date, venue substitution or nearby\nmove search occurs. Wick tick timing and unsupported drawings are not matched.\n\n`investigate_move` rechecks the event and reuses the web's five lead-up offsets,\nrecorded detector evidence and setup-combination builder. It consumes no allowance;\nhistorical snapshots retain their existing entitlement. Optional exact study scope\nand target return unrun `setup_first_rerun` documents, an allowance estimate and an\neditable workbench link. The default response omits duplicate source snapshots and detector candle bars,\nwith `full_sources: true` restoring the complete bytes. All reading values, exact\nsetup documents, source metadata, gaps and parity stay inspectable; a free re-read\nmay see a newer revision. Population counts and forward rates still require the existing\n`outcome_first` or `run_scan`, after a concrete proposal and explicit human approval.\nThe exact target stays separate from the setup predicate. Selected winning examples\nand same-period reruns remain exploratory; use a separate period before validation.\nReplay coverage and entitlement remain independent of research history.\n\nDeploy the web's `/api/v1/research/investigate/ground`, `/investigate` and `/evidence`\nroutes before releasing these MCP tools. The workbench on web b68c744 loads `rq`\nas an editable proposal and waits for Run. Do not use the new proposal links with older releases that execute on arrival.\nHistorical-marker and named-collection MCP parity remain separate work. The returned\nestimate is for each prepared setup, not a general quote endpoint.\n\nLocal deterministic tests exercise extracted observations and authenticated handlers\nwith fixtures. They are not image-model or vision-host acceptance. Follow the\n`test/screenshot-host-acceptance.md` cases in an actual vision-capable host before\nclaiming that upload-to-investigation works end to end.\n\n### Release 0.8.0\n\nAdds explicit screenshot grounding and move investigation, with compact source\nprojection by default and `full_sources: true` when the complete evidence is needed.\nThe host reads the images; the MCP validates structured observations and exact\nrecorded coordinates. Ambiguity requests clarification rather than inventing a move.\n\nSaved scans, cohorts, comparisons and outcome-first studies remain readable when\nallowance is exhausted. The web uses dedicated engine cache-read routes; a missing\nresult cannot start a new computation. A cache is revision-bound and may be evicted,\nso this is not a promise of permanent result storage. General replay access depends\non the recorded date, market and plan; research links do not confer an event grant.\n",
  "bytes": 23008,
  "sha": "d8af09cf499ece20a0f6001f036f4819cbb79d030914881b9b663297dad540ca",
  "repo_slug": "edgedepthhq/edgedepth-research-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_com_edgedepth_research_182fe088/readme"
}