HEADLESS RECORDS DOCS

MCP integration

Headless Records supports a local stdio MCP server for design-partner demos. It wraps the hosted REST API and preserves the same caveats, freshness status, request IDs, and provenance.

Scope

The MCP server lives in the API repo under /mcp. It calls the hosted API and requires HEADLESS_RECORDS_API_KEY. It does not connect directly to Postgres, SEC, Railway, or ingest internals.

Tools

get_freshness: GET /v1/freshness?freshness_window_hours=<value>
assess_insider_activity: GET /v1/insider-activity/{ticker}/assessment?period=<period>&freshness_window_hours=<hours>
get_filing_provenance: GET /v1/provenance/filing/{accession_number}

Cursor-compatible config

{
  "mcpServers": {
    "headless-records": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/headlessrecords/mcp/dist/index.js"],
      "env": {
        "HEADLESS_RECORDS_API_BASE_URL": "https://api.headlessrecords.dev",
        "HEADLESS_RECORDS_API_KEY": "hr_live_REPLACE_ME"
      }
    }
  }
}

Demo prompt

Use Headless Records to assess recent TSLA insider activity. Include freshness status, caveats, and provenance for one filing. Do not provide investment advice.

Limitations

Local stdio MCP only; this is not a hosted remote MCP server.
Requires a design-partner API key and sends it as X-API-Key.
Uses the hosted API and inherits API availability and rate limits.
Does not fetch SEC data live or run ingestion jobs.
Does not transform API output into investment advice.