Sec Filings MCP

What stagproject/sec-filings-mcp MCP server does

The stagproject/sec-filings-mcp MCP server gives MCP-compatible agents access to structured SEC EDGAR filing data. Its supported workflow is to search for filings, inspect a free sample, and purchase the complete filing JSON when the sample is sufficient to identify the needed document.

The server focuses on 10-K and 10-Q filings according to the project description. Filing data is read from Supabase views named fi_listings_portfolio and fi_listings_portfolio_compact. Those views are populated by the separate finance-factory pipeline, so this repository provides the MCP-facing service rather than documenting the upstream data-generation process in detail.

How it works

The stagproject/sec-filings-mcp MCP server exposes three MCP tools: search_filings, get_filing_sample, and purchase_filing. Production access uses MCP Streamable HTTP. The documented xpay endpoint adds billing and catalog access, while the Cloud Run upstream endpoint provides the server directly.

search_filings finds matching filings, and get_filing_sample returns a preview without requiring an xpay key when used through the documented Cloud Run trial or Glama sandbox. purchase_filing is the paid retrieval path. Payment uses x402 with USDC on Polygon; the README describes a 402 response and tx_hash redelivery for this operation.

An A2A Agent Card is available from the Cloud Run deployment for discovery. Native A2A JSON-RPC task handling is not currently implemented; agents invoke the service through MCP Streamable HTTP instead.

Setup and configuration

For local development, clone the repository, copy .env.example to .env, configure the Supabase and x402 settings, install dependencies with uv sync, and run uv run python mcp_server_finance.py --sse. The local MCP endpoint uses port 8081 by default in the documented example, with PORT configurable through the environment.

Before running the service, the project instructs operators to execute sql/fi_processed_transactions.sql once in the Supabase SQL Editor. The local process serves the MCP endpoint at /mcp. The repository also documents deployment to Google Cloud Run, including an unauthenticated Cloud Run configuration and environment variables supplied separately from the repository.

For hosted use, the xpay URL requires an xpay key in its query string. The Cloud Run trial endpoint supports search_filings and get_filing_sample without that key, while the Glama listing provides a browser-based sandbox.

Tools and capabilities

• Search structured SEC filing records with search_filings.
• Retrieve a free filing preview with get_filing_sample.
• Request complete filing JSON through purchase_filing.
• Discover the hosted service through its published A2A Agent Card.
• Invoke the production service using MCP Streamable HTTP.

Limitations and notes

The stagproject/sec-filings-mcp MCP server depends on Supabase data views and the finance-factory pipeline; the README does not describe it as a direct live query against the SEC website. Full filing retrieval is tied to x402 payment using Polygon USDC, so it is distinct from the no-key sample workflow. The xpay proxy requires an xpay key even when a tool is configured with a zero-dollar price, and the project notes that this is not the same as having no signup requirement.

The documented A2A interface currently supports discovery through an Agent Card, not native A2A JSON-RPC task execution. Operators deploying locally or to Cloud Run must provide the required Supabase and x402 configuration themselves, and should not commit the environment file.