MCP server
A local stdio MCP server gives agents direct access to the API as tools. It wraps the hosted REST API and preserves the same caveats, freshness status, request IDs, and provenance.
Scope
The MCP server is open source at github.com/jgmcalpine/headless-records-mcp. It is a thin client for this hosted API: it validates tool input, calls api.headlessrecords.dev with your API key, and returns responses with all caveats, provenance, and request IDs preserved. It exposes three tools: get_freshness, assess_insider_activity, and get_filing_provenance.
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}
MCP client configuration
{
"mcpServers": {
"headless-records": {
"command": "node",
"args": ["/absolute/path/to/dist/index.js"],
"env": { "HEADLESS_RECORDS_API_KEY": "hr_live_REPLACE_ME" }
}
}
}Setup, tool schemas, and error behavior are documented in the repo README. An API key is required — request design partner access.
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.