What can you do with this server?

This server provides structured, non-advisory access to public SEC Form 4 insider filing data via the Headless Records API. Here's what you can do: * Check data freshness (get_freshness): Retrieve the freshness status of the watched-ticker universe, indicating how up-to-date the SEC filing coverage is, with a configurable freshness window (1–168 hours). * Assess insider activity (assess_insider_activity): Get a deterministic, factual summary of reported SEC Form 4 insider trading activity for a specific ticker over a chosen time period (30, 90, or 180 days), without any investment recommendations or trading signals. * Retrieve filing provenance (get_filing_provenance): Look up the source provenance of a specific imported SEC Form 4 filing by accession number, including the source document URL, retrieval timestamp, and SHA-256 hash. All interactions are non-advisory and confined to publicly available SEC Form 4 data from a bounded, watched-ticker universe, and do not constitute financial advice.

How do I use headless-records-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@headless-records-mcp assess insider activity for AAPL" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

headless-records-mcp

by jgmcalpine

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

Headless Records MCP Server

A local Model Context Protocol (MCP) stdio server that gives agents structured, non-advisory access to public SEC Form 4 insider filing data via the hosted Headless Records API.

The server is a thin wrapper: it validates tool input, calls https://api.headlessrecords.dev, and returns the API's JSON responses as formatted text. It does not call SEC directly, does not connect to a database, and does not run ingestion jobs.

Full API documentation: headlessrecords.dev · OpenAPI spec

Safety and Scope

Responses summarize public SEC Form 4 filing data from a bounded, watched-ticker universe. They do not imply full-market coverage.
Output is not financial advice. The server provides no buy, sell, hold, bullish, bearish, price prediction, alpha, trading signal, or investment recommendation guidance.
API caveats, methodology notes, request IDs, timestamps, and source provenance are preserved in tool output so agents can show context rather than over-compress results.

Related MCP server: sec-edgar-mcp

Requirements

Node.js 20 or later (uses the built-in fetch)
A Headless Records API key (hr_live_ prefix) — request design partner access
No key yet? Try the open preview endpoint:

  curl https://api.headlessrecords.dev/v1/ticker/TSLA/preview

Install and Build

npm install
npm run build

The compiled server is written to dist/index.js.

Configuration

The server is configured entirely through environment variables read from the process. Export them in your shell or set them in your MCP client config. (.env.example is a reference file only; the server does not auto-load .env.)

Required:

HEADLESS_RECORDS_API_KEY — your API key, sent as the X-API-Key header.

Optional:

HEADLESS_RECORDS_API_BASE_URL — defaults to https://api.headlessrecords.dev.
HEADLESS_RECORDS_TIMEOUT_MS — per-request timeout, defaults to 10000.

Do not commit real API keys.

Running

Run from source:

HEADLESS_RECORDS_API_KEY=hr_live_REPLACE_ME npm start

Run the built stdio server:

HEADLESS_RECORDS_API_KEY=hr_live_REPLACE_ME node /absolute/path/to/dist/index.js

MCP Client Configuration

Example configuration for Cursor, Claude Desktop, or any MCP client, after npm run build:

{
  "mcpServers": {
    "headless-records": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"],
      "env": {
        "HEADLESS_RECORDS_API_KEY": "hr_live_REPLACE_ME"
      }
    }
  }
}

Tools

`get_freshness`

Returns freshness status for the configured watched-ticker universe.

{
  "freshness_window_hours": 24
}

freshness_window_hours (optional integer, 1–168, default 24)

Calls GET /v1/freshness.

`assess_insider_activity`

Returns a deterministic, non-advisory summary of reported SEC Form 4 insider activity for a ticker. Tickers are normalized to uppercase before the API call.

{
  "ticker": "TSLA",
  "period": "90d",
  "freshness_window_hours": 24
}

ticker (required string)
period (optional, one of 30d, 90d, 180d, default 90d)
freshness_window_hours (optional integer, 1–168, default 24)

Calls GET /v1/insider-activity/{ticker}/assessment.

`get_filing_provenance`

Returns source provenance for an imported SEC Form 4 filing, including the source document URL, retrieval timestamp, and SHA-256 hash when available.

{
  "accession_number": "0000001001-26-000123"
}

accession_number (required string)

Calls GET /v1/provenance/filing/{accession_number}.

Error Behavior

Tool errors are returned as structured JSON with a stable code field:

Missing, invalid, or revoked API keys surface as unauthorized (HTTP 401).
Rate limits surface as rate_limited (HTTP 429), including retry_after when the API provides it.
Timeouts, network failures, and invalid responses surface as timeout, network_error, and invalid_json.
API request IDs are preserved in error output when available.
Raw hr_live_... API keys are redacted from all error text.

Development

npm test

Tests run with Vitest and use mocked HTTP; they never call the live API.

Known Limitations

Local stdio server only; this is not a hosted remote MCP server.
Requires a valid HEADLESS_RECORDS_API_KEY and inherits the API's per-key rate limits.
Coverage is bounded to the watched-ticker universe and imported filings; it does not fetch SEC data live.
Does not manage watched tickers, billing, or authentication flows.
Returns formatted JSON text; it does not transform API output into advice.

Available Tools

3 tools

assess_insider_activityB

Return a deterministic, non-advisory summary of reported public SEC Form 4 insider activity for a ticker. This uses bounded watched-ticker and imported-filing coverage and does not provide buy, sell, hold, bullish, bearish, price prediction, alpha, trading signal, or investment recommendation guidance.

ParametersJSON Schema

Name	Required	Default
`period`	No	90d
`ticker`	Yes
`freshness_window_hours`	No

TDQS

B3.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description provides substantive behavioral disclosure: it is 'deterministic,' 'non-advisory,' and explicitly states what it does NOT provide (buy, sell, hold, etc.). It mentions coverage limitations. This goes well beyond basic transparency, though it could add details on error handling or data freshness.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with no filler. The first sentence front-loads the core purpose, and the second sentence effectively clarifies limitations. Every word serves a purpose, achieving high conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite the clear purpose, the description lacks completeness: no output schema exists, and the summary format is not described. The three parameters are left unexplained, and there is no guidance on parameter interactions or expected behavior. Important context about the 'bounded' coverage is vague.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description does not explain any of the three parameters (ticker, period, freshness_window_hours). Schema coverage is 0%, and the description adds no meaning beyond the input schema. For example, it doesn't describe how 'period' affects the summary or what 'freshness_window_hours' controls.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns a 'deterministic, non-advisory summary of reported public SEC Form 4 insider activity for a ticker.' It specifies the resource (insider activity) and verb (return summary), and distinguishes from investment advice. However, it does not explicitly differentiate from sibling tools, though they appear unrelated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for SEC Form 4 insider activity but does not provide explicit guidance on when to use versus alternatives. It notes that the tool uses 'bounded watched-ticker and imported-filing coverage' and does not offer recommendations, which partially clarifies scope. No direct when-not or sibling comparisons are given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_filing_provenanceB

Return source provenance for an imported SEC Form 4 filing, including source document URL, retrieval timestamp, and SHA-256 hash when available. This summarizes public SEC filing data provenance and does not provide buy, sell, hold, price prediction, or investment recommendation guidance.

ParametersJSON Schema

Name	Required	Description	Default
`accession_number`	Yes

TDQS

B3.1/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It states the tool summarizes 'public SEC filing data provenance', implying a read-only operation. It includes a disclaimer about not providing investment advice. However, it does not explicitly declare read-only status, rate limits, or authentication requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description consists of two sentences with no redundancy. The first sentence provides the core purpose, and the second adds a necessary disclaimer. Every word serves a purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the absence of annotations, output schema, and parameter descriptions, the description is incomplete. It mentions return fields (URL, timestamp, hash) but does not address error handling, format, or how the parameter is used. The agent may not be able to reliably invoke the tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has one required string parameter 'accession_number' with minLength 1, but the description does not explain its meaning, format, or how it relates to provenance. With 0% schema description coverage, the description should clarify the parameter, but it fails to do so.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Return' and the resource 'source provenance for an imported SEC Form 4 filing'. It specifies what is included (URL, timestamp, hash). It distinguishes from siblings like 'assess_insider_activity' and 'get_freshness' by focusing on provenance.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus the sibling tools. It does not mention prerequisites, constraints, or specific contexts. The agent would need to infer usage from the tool name and sibling names.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_freshnessC

Return freshness status for the configured Headless Records watched ticker universe. This summarizes public SEC filing data coverage status, does not imply full-market coverage, and the watched ticker coverage is bounded.

ParametersJSON Schema

Name	Required	Description	Default
`freshness_window_hours`	No

TDQS

C2.9/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses that coverage is not full-market and bounded, adding context beyond the name. However, lacks mention of read-only nature, authentication requirements, or error behavior. Annotations are absent, so description carries full burden but falls short.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with no fluff. First sentence delivers primary purpose, second adds important caveats. Efficient and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, description does not describe return format or example output. Also missing parameter guidance. Only covers purpose and a single caveat, leaving significant gaps for agent decision-making.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% and description does not mention the single parameter (freshness_window_hours). No additional meaning provided beyond what the schema already states.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it returns freshness status for a specific universe (Headless Records watched ticker universe) and distinguishes from siblings by focusing on coverage status rather than insider activity or filing provenance.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool vs alternatives (assess_insider_activity, get_filing_provenance). No explicit usage conditions or when-not-to-use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

3 tool updatesv0.1.0Jul 8, 2026
- First observedassess_insider_activity
- First observedget_filing_provenance
- First observedget_freshness

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.4/5.0

Scored 2026-07-08 03:55 across 3 tools

Disambiguation5/5

Each tool targets a distinct aspect: insider activity summary, filing provenance, and data freshness. No overlap.

Naming Consistency5/5

All tools follow a consistent verb_noun pattern with snake_case: assess_insider_activity, get_filing_provenance, get_freshness.

Tool Count4/5

3 tools is slightly below typical range, but the scope is narrow and each tool serves a clear purpose. No unnecessary tools.

Completeness3/5

Core functions are covered, but missing features like listing tickers or raw filing data. The bounded nature partly justifies the gaps.

Maintenance

ActivityStale

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

Filings Intel MCP A
com.datakoot
SEC EDGAR filings for AI agents: company lookup, filings, financials, insider trades. No keys.
Finance Open Data Research & Data
51
Filings Intel MCP A
io.github.selflabbs
SEC EDGAR filings for AI agents: company lookup, filings, financials, insider trades. No keys.
Finance Government Data Open Data
2
ko-mcp A
io.github.SharpLu
Real SEC, 13F, insider, congress & macro data your AI agent can cite. Hosted MCP, 24 tools.
Finance Government Data
242
Edgrapi — US Government Data API A
com.edgrapi.api
US government data as clean JSON for AI agents: SAM.gov contract opportunities, USAspending awards, Grants.gov grants, House STOCK Act trades, and SEC EDGAR filings (Form 4 insider trades, 8-K events, 13F holdings, 13D/G stakes, XBRL fundamentals, 10-K/10-Q sections). 19 read-only tools. Data is as fresh as each source publishes; congressional trades lag up to 45 days and report dollar ranges (House only). Free tier, no card.
Finance Government Data Open Data
192

Related MCP Servers

mcp-edgar
Finance Government Data Open Data
cmanohar
A
license
Not graded
quality
D
maintenance
Enables LLMs to access SEC EDGAR data: search filings, extract sections, pull structured financials, and track insider transactions.
Updated 5 months ago (2026-04-28 21:20 UTC)
24 npm
MIT
sec-edgar-mcp
Finance Government Data Open Data
guptaprakhariitr
A
license
Not graded
quality
D
maintenance
Hosted MCP server that gives AI agents real-time access to SEC EDGAR filings search, 10-K/8-K reading, XBRL financial facts, and insider-trade (Form 4) alerts.
Updated 3 months ago (2026-06-11 08:39 UTC)
11 npm
1
MIT
AlphaSMO Tools MCP Serverofficial
Finance Government Data
alphasmo
A
license
Not graded
quality
B
maintenance
Provides access to SEC EDGAR 13F institutional holdings, Form 4 insider trading, and smart money convergence signals for AI agents via the Model Context Protocol.
Updated a month ago (2026-08-12 15:09 UTC)
27 npm
2
MIT
vigia-edgar
Finance Government Data
filingtape
F
license
Not graded
quality
D
maintenance
An always-on engine that watches SEC EDGAR for insider trading (Form 4) and material event (8-K) filings, alerting users through AI agents via MCP tools.
Updated 3 months ago (2026-06-16 09:59 UTC)
-

Headless Records MCP Server

Safety and Scope

Requirements

Install and Build

Configuration

Running

MCP Client Configuration

Tools

get_freshness

assess_insider_activity

get_filing_provenance

Error Behavior

Development

Known Limitations

Available Tools

TDQS

TDQS

TDQS

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

mcp-edgar

sec-edgar-mcp

AlphaSMO Tools MCP Serverofficial

vigia-edgar

`get_freshness`

`assess_insider_activity`

`get_filing_provenance`