# HyperDD MCP connection guide

HyperDD provides an authenticated remote MCP service at
`https://hyperdd.com/mcp`. It serves evidence and retained research;
analysis runs in your host session.

## Register the MCP server

Obtain a token from an operator. Export it as `HYPERDD_TOKEN` in the environment
that starts your client; do not paste it into shared configuration or logs.
This is operator-issued bearer authentication, not an OAuth login flow.

Codex (inspect `codex mcp get hyperdd` before replacing an existing entry):

```sh
codex mcp add hyperdd --url https://hyperdd.com/mcp \
  --bearer-token-env-var HYPERDD_TOKEN
```

Set `tool_timeout_sec = 120` in the existing `[mcp_servers.hyperdd]` section
of your Codex configuration if you need the service's full request window.
Preserve other entries. GUI clients need the token available in their own
launch environment, not just a separate terminal.

Claude Code (inspect `claude mcp get hyperdd` first):

```sh
claude mcp add --transport http hyperdd https://hyperdd.com/mcp \
  --header "Authorization: Bearer $HYPERDD_TOKEN"
```

This stores a header in Claude's local configuration; protect that file.
No universal Claude Desktop/Cursor JSON format is assumed. Use each client's
HTTP connector instructions; OAuth-only connectors cannot use this bearer setup.

## Install the companion skill separately

[Download SKILL.md](https://hyperdd.com/skills/hyperdd/SKILL.md).
It is one UTF-8 Markdown file with YAML frontmatter and needs no scripts.
Inspect an existing `hyperdd/SKILL.md` before replacing it. For a new project
installation, download and review the file, then place it at
`.agents/skills/hyperdd/SKILL.md` for Codex or
`.claude/skills/hyperdd/SKILL.md` for Claude Code. Reload skill discovery in your
client. These steps do not register MCP or grant access to private data.

```sh
curl --fail --max-time 30 \
  https://hyperdd.com/skills/hyperdd/SKILL.md \
  --output /tmp/hyperdd-SKILL.md
```

## Runnable HTTP example and outputs

For a read-only catalog check, direct HTTP is also supported:

```sh
curl --fail --max-time 120 https://hyperdd.com/mcp \
  -H "Authorization: Bearer $HYPERDD_TOKEN" \
  -H 'Content-Type: application/json' -H 'Accept: application/json' \
  -H 'MCP-Protocol-Version: 2026-07-28' -H 'Mcp-Method: tools/list' \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

For a representative call, set `Mcp-Method: tools/call`, add
`Mcp-Name: evidence_snapshot`, and use:

```json
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"evidence_snapshot","arguments":{"ticker":"NVDA","limit":10}}}
```

Successful tool replies contain `result.content` text blocks whose text is
JSON. Inventory replies include `version`, `files`, `next_cursor`, and explicit
availability/truncation flags. Follow cursors with the same version.
An unavailable snapshot is a valid, explicitly missing result, not a research
conclusion. Read the companion skill for limits, exact bytes and citation rules.
HTTP 401 means missing/wrong credentials; JSON-RPC `-32602` means bad arguments;
server errors are not evidence. No automatic retry of `gather` or `jev_evaluate`.

## Data handling and execution limits

Source evidence and historical publications remain in private R2 storage.
Downloads use expiring signed URLs; treat them as credentials. Read results
enter your host agent's context. Gather writes evidence and starts paid work.
Jev sends the submitted artifact and evidence to the configured TypeSafe
provider; the adapter makes no artifact writes, but provider retention is not
verified. Only `jev-rating` produces investment stars. Neither discovery nor
skill installation authorizes paid calls, publication or broader data access.

The service request timeout is 120 seconds. A client timeout/disconnect does not
prove a synchronous read or an already-launched ingestion job stopped. Check
`status` before any decision to retry a gather. There is no resumable SSE stream
or server session; older clients can receive one SSE message per response. Large sources use bounded read chunks or signed downloads.

## Compatibility and verification

The existing custom server is retained to preserve its deployed contracts.
The current specification is [MCP 2026-07-28](https://modelcontextprotocol.io/specification/2026-07-28).
Verified locally with official Python SDK 2.2.0: legacy initialization negotiated
2025-11-25, modern server/discover returned 2026-07-28, all 15 tools listed,
ping and skills_list completed, and invalid arguments were rejected.
Storage-backed reads and paid calls were not tested against production.
These were local client checks using fixture credentials; this guide does not
claim universal client or full latest-spec conformance. Static bearer tokens do not implement MCP's
OAuth authorization profile. Production changes require deployment verification.

References: [official Python SDK](https://github.com/modelcontextprotocol/python-sdk),
[Codex MCP](https://developers.openai.com/codex/mcp/),
[Codex skills](https://developers.openai.com/codex/skills/),
[Claude Code MCP](https://code.claude.com/docs/en/mcp),
[Claude Code skills](https://code.claude.com/docs/en/skills).

## Tools

Required parameters are unbracketed; brackets denote optional parameters.
The following catalog is generated from the exact deployed registry.

### get_coverage(ticker)
Coverage report for one ticker: which manifest sources landed.
  ticker: Ticker symbol

### gather(ticker, [source], [force])
Start a corpus fetch for one ticker. Returns a Modal call id.
  ticker: Ticker symbol
  source: Limit to one source name
  force: Re-fetch even when the file already exists. Requires `source`.

### status(no arguments)
State of the most recent manual gather run.

### raw_list(ticker, [revision], [prefix])
List the raw evidence files fetched for a ticker, with sizes. Start here, then raw_manifest for the files you want.
  ticker: Ticker symbol
  revision: Publication revision for exact cited bytes
  prefix: Exact file path or directory; not a filename prefix

### raw_manifest(ticker, [revision], [prefix], [expires_in])
Signed download URLs for a ticker's raw evidence. Use this to GET the files yourself; the bytes never enter the conversation.
  ticker: Ticker symbol
  revision: Publication revision for exact cited bytes
  prefix: Exact file path or directory; not a filename prefix
  expires_in: URL lifetime in seconds, max 86400

### evidence_snapshot(ticker, [version], [download], [cursor], [limit])
Return a paginated immutable inventory. Set download=true for signed URLs; follow every next_cursor with the pinned version to download the complete corpus.
  ticker: Ticker symbol
  version: Pinned evidence version
  download: Include 15-minute signed immutable download URLs
  cursor: Last returned path
  limit: Page size, max 200

### evidence_read(ticker, path, [version], [max_bytes], [start])
Read bounded bytes from one immutable source snapshot with a stable locator.
  ticker: Ticker symbol
  path: Snapshot-relative source path
  version: Evidence version; defaults to current
  max_bytes: Source bytes per chunk, max 64000; includes text and exact base64
  start: Byte offset for continuation

### evidence_search(ticker, query, [version], [max_results], [context_chars], [prefix], [cursor], [max_scan_bytes])
Search bounded source text in one immutable evidence snapshot.
  ticker: Ticker symbol
  version: Evidence version; defaults to current
  max_results: Match cap, max 50
  context_chars: Match context cap, max 2000
  prefix: Limit search to a snapshot path or directory
  cursor: Opaque next_cursor from prior search; repeat version, query and prefix
  max_scan_bytes: Total scan budget, max 4000000

### evidence_changes(ticker, from_version, [to_version], [cursor], [limit])
Compare immutable evidence source hashes since a pinned version.
  ticker: Ticker symbol
  from_version: Prior evidence version
  to_version: Target version; defaults to current
  cursor: Last changed path
  limit: Page size, max 200

### wiki_read(ticker, [full])
Read the wiki page for a ticker: thesis, drivers, dependencies.
  ticker: Ticker symbol
  full: Return the whole page, not a summary

### wiki_neighbors(ticker, [min_confidence])
Companies this ticker depends on or is depended on by.
  ticker: Ticker symbol
  min_confidence: Drop edges below this, 0-1

### wiki_search(query)
Full-text search across every wiki page.

### skills_list(no arguments)
List the CPE equity-research skills and the files each one has.

### skill_read(skill, [path])
Read one skill's SKILL.md, or a named file under it such as references/lenses.md.
  skill: Skill name from skills_list
  path: Relative file, defaults to SKILL.md

### jev_evaluate(kind, artifact, [evidence], [metadata])
Run a metered Jev evaluation using a research review skill. Supply the artifact and bounded cited evidence. Only kind jev-rating returns investment stars; other kinds return qualitative findings. Missing evidence or unavailable Jev is not a pass. No research agent, publication or background job is started.
  artifact: Text or structured artifact; jev-rating requires fixed memo text
  evidence: Evidence records using the review skill's schema
  metadata: Source/version metadata; rating requires its rubric inputs