Get SEC Filing
get_sec_filingRetrieve an SEC filing by its accession number. Get filing metadata including company info, form type, filing date, and document URLs.
Instructions
Retrieve a single SEC filing by its accession number. Returns full filing metadata including company info, form type, filing date, and document URLs.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| accession_number | Yes | SEC accession number (e.g. 0001652044-25-000001). Dashes are optional. |
Implementation Reference
- src/tools/sec.ts:117-153 (handler)Handler function for the get_sec_filing tool. Takes an accession_number parameter, makes a GET request to /api/v1/sec/filings/{accession_number}, and returns the filing data as JSON. Handles 404 and other error cases.
server.registerTool( "get_sec_filing", { title: "Get SEC Filing", description: "Retrieve a single SEC filing by its accession number. Returns full filing metadata " + "including company info, form type, filing date, and document URLs.", inputSchema: { accession_number: z .string() .describe( "SEC accession number (e.g. 0001652044-25-000001). Dashes are optional.", ), }, }, async ({ accession_number }) => { const res = await apiGet<SecFilingResponse>( `/api/v1/sec/filings/${encodeURIComponent(accession_number)}`, ); if (!res.ok) { const msg = res.status === 404 ? `Filing ${accession_number} not found.` : `API error (${res.status}): ${JSON.stringify(res.data)}`; return { content: [{ type: "text" as const, text: msg }], isError: res.status !== 404, }; } return { content: [ { type: "text" as const, text: JSON.stringify(res.data.data, null, 2) }, ], }; }, - src/tools/sec.ts:20-23 (schema)TypeScript interface defining the response shape for the get_sec_filing API call.
interface SecFilingResponse { dataset: string; data: Record<string, unknown>; } - src/tools/sec.ts:38-233 (registration)The registerSecTools function registers all SEC-related tools on the MCP server, including get_sec_filing.
export function registerSecTools(server: McpServer): void { // ── Search filings ─────────────────────────────────────────────────────── server.registerTool( "search_sec_filings", { title: "Search SEC Filings", description: "Search SEC EDGAR filings by CIK number, form type (10-K, 10-Q, 8-K, etc.), " + "company name, and date range. Returns filing metadata including accession number, " + "filing date, and document URLs. Source: SEC EDGAR, updated every 15 minutes.", inputSchema: { cik: z .string() .optional() .describe( "Central Index Key — SEC's unique company identifier (e.g. 0001652044 for Alphabet)", ), form_type: z .string() .optional() .describe( "SEC form type (e.g. 10-K, 10-Q, 8-K, S-1, DEF 14A). Case-insensitive.", ), company_name: z .string() .optional() .describe("Company name to search for (partial match)"), date_from: z .string() .optional() .describe("Start date for filing date range (YYYY-MM-DD)"), date_to: z .string() .optional() .describe("End date for filing date range (YYYY-MM-DD)"), limit: z .number() .int() .min(1) .max(100) .optional() .describe("Maximum number of results (default 25, max 100)"), }, }, async ({ cik, form_type, company_name, date_from, date_to, limit }) => { const res = await apiGet<SecFilingsResponse>("/api/v1/sec/filings", { cik, form_type, company_name, date_from, date_to, limit: limit ?? 25, }); if (!res.ok) { return { content: [ { type: "text" as const, text: `API error (${res.status}): ${JSON.stringify(res.data)}`, }, ], isError: true, }; } const { count, data } = res.data; const summary = `Found ${count} SEC filing(s).`; const json = JSON.stringify(data, null, 2); return { content: [{ type: "text" as const, text: `${summary}\n\n${json}` }], }; }, ); // ── Single filing lookup ───────────────────────────────────────────────── server.registerTool( "get_sec_filing", { title: "Get SEC Filing", description: "Retrieve a single SEC filing by its accession number. Returns full filing metadata " + "including company info, form type, filing date, and document URLs.", inputSchema: { accession_number: z .string() .describe( "SEC accession number (e.g. 0001652044-25-000001). Dashes are optional.", ), }, }, async ({ accession_number }) => { const res = await apiGet<SecFilingResponse>( `/api/v1/sec/filings/${encodeURIComponent(accession_number)}`, ); if (!res.ok) { const msg = res.status === 404 ? `Filing ${accession_number} not found.` : `API error (${res.status}): ${JSON.stringify(res.data)}`; return { content: [{ type: "text" as const, text: msg }], isError: res.status !== 404, }; } return { content: [ { type: "text" as const, text: JSON.stringify(res.data.data, null, 2) }, ], }; }, ); // ── Company search ─────────────────────────────────────────────────────── server.registerTool( "search_sec_companies", { title: "Search SEC Companies", description: "Search for companies registered with the SEC by name. Returns CIK numbers, " + "company names, and filing counts. Useful for finding a company's CIK before " + "searching their filings.", inputSchema: { search: z .string() .min(2) .describe("Company name to search for (at least 2 characters)"), }, }, async ({ search }) => { const res = await apiGet<SecCompaniesResponse>("/api/v1/sec/companies", { search, }); if (!res.ok) { return { content: [ { type: "text" as const, text: `API error (${res.status}): ${JSON.stringify(res.data)}`, }, ], isError: true, }; } const { count, data } = res.data; const summary = `Found ${count} compan${count === 1 ? "y" : "ies"}.`; const json = JSON.stringify(data, null, 2); return { content: [{ type: "text" as const, text: `${summary}\n\n${json}` }], }; }, ); // ── Dataset stats ──────────────────────────────────────────────────────── server.registerTool( "sec_stats", { title: "SEC Dataset Statistics", description: "Get statistics about the SEC filings dataset: total filings, form type breakdown, " + "date range, and last updated timestamp. Free endpoint, no payment required.", inputSchema: {}, }, async () => { const res = await apiGet<SecStatsResponse>("/api/v1/sec/stats"); if (!res.ok) { return { content: [ { type: "text" as const, text: `API error (${res.status}): ${JSON.stringify(res.data)}`, }, ], isError: true, }; } return { content: [ { type: "text" as const, text: JSON.stringify(res.data, null, 2) }, ], }; }, ); } - src/index.ts:33-61 (registration)The createMcpServer function in index.ts calls registerSecTools(server) to register all SEC tools on the MCP server.
function createMcpServer() { const server = new McpServer({ name: "verilex-data", version: "0.3.3", }); registerNpiTools(server); registerSecTools(server); registerPacerTools(server); registerWeatherTools(server); registerOtcTools(server); registerTrademarkTools(server); registerPatentTools(server); registerCompanyTools(server); registerCryptoTools(server); registerSanctionsTools(server); registerWhaleTools(server); registerLabelTools(server); registerHolderTools(server); registerDexTools(server); registerContractTools(server); registerPmTools(server); registerPmArbTools(server); registerPmResolutionTools(server); registerEconTools(server); registerPmMicroTools(server); return server; } - src/client.ts:44-76 (helper)The apiGet helper function used by the get_sec_filing handler to make HTTP GET requests to the Verilex API.
export async function apiGet<T = unknown>( path: string, params?: Record<string, string | number | undefined>, ): Promise<ApiResponse<T>> { const url = buildUrl(path, params); const headers: Record<string, string> = { Accept: "application/json", "User-Agent": "verilex-mcp-server/0.1.0", }; // Forward x402 payment token if present in env (for paid endpoints) const paymentToken = process.env.VERILEX_PAYMENT_TOKEN; if (paymentToken) { headers["X-Payment-Token"] = paymentToken; } const res = await fetch(url, { headers }); const data = (await res.json()) as T; const stale = res.headers.get("X-Data-Stale"); const lastUpdated = res.headers.get("X-Data-Last-Updated"); const ageSeconds = res.headers.get("X-Data-Age-Seconds"); return { ok: res.ok, status: res.status, data, stale: stale === "true", lastUpdated: lastUpdated ?? undefined, ageSeconds: ageSeconds ? Number(ageSeconds) : undefined, }; }