SecFeed for AI Agents reference | SecFeed for developers

Endpoints

/mcp

POSThttps://secfeedapi.com/mcp

MCP server over HTTP (JSON-RPC). Or run locally over stdio: python3 -m fw.mcp. 26 tools covering every API above.

Parameter	Type	Description	Example
`Authorization`required	header	Bearer YOUR_KEY. Required on every request, including initialize.	`Bearer YOUR_KEY`
`Content-Type`required	header	application/json.	`application/json`
`jsonrpc`required	string	Always 2.0.	`2.0`
`id`	integer or string	Request id echoed in the response. Omit it for notifications.	`1`
`method`required	string	initialize, tools/list, tools/call or ping. Notifications such as notifications/initialized are accepted.	`tools/list`
`params`	object	initialize: protocolVersion, capabilities, clientInfo. tools/call: name and arguments.	`{"name":"search_filings","arguments":{"query":"ticker:NVDA"}}`

A JSON array of requests is answered with an array of responses (batching).
Notifications (no id) get 202 Accepted with an empty body.
GET /mcp returns 405: the server does not open a server-sent event stream, so clients use POST only.
initialize echoes the protocolVersion the client asks for; the server's own version is 2025-06-18.
tools/call returns the tool's JSON as a text content block, cut at 200000 characters. Tool failures come back as isError true with the message, not as a JSON-RPC error.
Unknown methods return JSON-RPC error -32601. Each request counts as one API call against your plan.

Request examples

Every response below is real output from the API, trimmed to the first records.

Initialize a session

The first request every client sends. The result names the server and says it offers tools.

curl -X POST "https://secfeedapi.com/mcp" -H "Authorization: Bearer $SECFEED_KEY" -H "Content-Type: application/json" -d '{...}'

import os, requests

r = requests.get(
    "https://secfeedapi.com/mcp",
    headers={"Authorization": f"Bearer {os.environ['SECFEED_KEY']}"},
    timeout=60,
)
r.raise_for_status()
print(r.json())

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": {
      "tools": {}
    },
    "serverInfo": {
      "name": "secfeed",
      "version": "0.1"
    }
  }
}

List the tools

Returns every tool with its description and JSON Schema input, ready for an agent to choose from.

curl -X POST "https://secfeedapi.com/mcp" -H "Authorization: Bearer $SECFEED_KEY" -H "Content-Type: application/json" -d '{...}'

import os, requests

r = requests.get(
    "https://secfeedapi.com/mcp",
    headers={"Authorization": f"Bearer {os.environ['SECFEED_KEY']}"},
    timeout=60,
)
r.raise_for_status()
print(r.json())

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "search_filings",
        "description": "Search every EDGAR filing with a Lucene-style query, e.g. ticker:AAPL AND formType:\"10-K\" AND filedAt:[2026-01-01 TO 2026-12-31].",
        "inputSchema": {
          "type": "object",
          "properties": {
            "query": {
              "type": "string",
              "description": "Lucene-style query"
            },
            "size": {
              "type": "integer",
              "description": "max results, default 20"
            },
            "from": {
              "type": "integer",
              "description": "offset"
            }
          }
        }
      },
      {
        "name": "full_text_search",
        "description": "Search the full text of every filing and exhibit since 2001. Use quotes for exact phrases.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "query": {
              "type": "string",
              "description": "words or \"exact phrase\""
            },
            "formTypes": {
              "type": "string",
              "description": "comma separated, e.g. 10-K,8-K"
            },
            "startDate": {
              "type": "string",
              "description": "YYYY-MM-DD"
            },
            "endDate": {
              "type": "string",
              "description": "YYYY-MM-DD"
            }
          }
        }
      }
    ]
  }
}

Call a tool

Runs search_filings with a Lucene query; the filing search JSON comes back as text inside result.content.

curl -X POST "https://secfeedapi.com/mcp" -H "Authorization: Bearer $SECFEED_KEY" -H "Content-Type: application/json" -d '{...}'

import os, requests

r = requests.get(
    "https://secfeedapi.com/mcp",
    headers={"Authorization": f"Bearer {os.environ['SECFEED_KEY']}"},
    timeout=60,
)
r.raise_for_status()
print(r.json())

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"total\": {\"value\": 25, \"relation\": \"eq\"}, \"filings\": [{\"accessionNo\": \"0001045810-26-000021\", \"cik\": \"1045810\", \"ticker\": \"NVDA\", \"companyName\": \"NVIDIA CORP\", \"formType\": \"10-K\", \"filedAt\": \"2026-02-25\", \"linkToTxt\": \"https://www.sec.gov/Archives/edgar/data/1045810/0001045810-2..."
      }
    ]
  }
}

Response fields

Field	Type	Meaning
`jsonrpc`	string	Always 2.0.
`id`	integer or string	The id from the request.
`result`	object	Present on success.
`result.protocolVersion`	string	initialize only: the protocol version in use.
`result.capabilities.tools`	object	initialize only: the server offers tools.
`result.serverInfo.name`	string	initialize only: secfeed.
`result.serverInfo.version`	string	initialize only: server version.
`result.tools[]`	array	tools/list only: one entry per tool.
`result.tools[].name`	string	Tool name to pass to tools/call.
`result.tools[].description`	string	What the tool returns, written for the model.
`result.tools[].inputSchema`	object	JSON Schema of the tool arguments.
`result.content[]`	array	tools/call only: the tool output.
`result.content[].type`	string	Always text.
`result.content[].text`	string	The tool's JSON response as a string, or an error message.
`result.isError`	boolean	tools/call only: true when the tool failed.
`error.code`	integer	JSON-RPC error code: -32601 unknown method, -32603 internal error.
`error.message`	string	Error description.

Methods

Method	What it does
initialize	Starts a session and reports server capabilities
notifications/initialized	Client notification, answered with 202
tools/list	Lists every tool with its input schema
tools/call	Runs one tool with arguments
ping	Returns an empty result

How to

How do I add SecFeed to Claude Code?

Run claude mcp add --transport http secfeed https://secfeedapi.com/mcp --header "Authorization: Bearer YOUR_KEY". Setup pages for other clients are under /mcp/.

curl -X POST "https://secfeedapi.com/mcp" -H "Authorization: Bearer $SECFEED_KEY" -H "Content-Type: application/json" -d '{...}'

How do I check my key works before configuring a client?

POST a tools/list request with curl. A 401 means the key is missing or wrong.

curl -X POST "https://secfeedapi.com/mcp" -H "Authorization: Bearer $SECFEED_KEY" -H "Content-Type: application/json" -d '{...}'

How do I see the inputs a tool accepts?

Each entry in tools/list has an inputSchema with the parameters and their descriptions.

curl -X POST "https://secfeedapi.com/mcp" -H "Authorization: Bearer $SECFEED_KEY" -H "Content-Type: application/json" -d '{...}'

How do I call a tool without an agent?

Send tools/call with the tool name and an arguments object; the response is the same JSON the REST endpoint returns, as text.

curl -X POST "https://secfeedapi.com/mcp" -H "Authorization: Bearer $SECFEED_KEY" -H "Content-Type: application/json" -d '{...}'

How do I send several requests at once?

POST a JSON array of requests; you get an array of responses in the same order.

curl -X POST "https://secfeedapi.com/mcp" -H "Authorization: Bearer $SECFEED_KEY" -H "Content-Type: application/json" -d '{...}'

How do I check the connection is alive?

Send ping; the result is an empty object.

curl -X POST "https://secfeedapi.com/mcp" -H "Authorization: Bearer $SECFEED_KEY" -H "Content-Type: application/json" -d '{...}'

What happens when a tool fails?

The response still has a result, with isError true and the reason in the text. Unknown tool names fail this way.

curl -X POST "https://secfeedapi.com/mcp" -H "Authorization: Bearer $SECFEED_KEY" -H "Content-Type: application/json" -d '{...}'

Does the server support resources or prompts?

No, only tools. resources/list and other methods return error -32601.

curl -X POST "https://secfeedapi.com/mcp" -H "Authorization: Bearer $SECFEED_KEY" -H "Content-Type: application/json" -d '{...}'

Why does GET /mcp return 405?

The server answers every request in the POST response and does not keep an event stream open. MCP clients handle this automatically.

curl -X POST "https://secfeedapi.com/mcp" -H "Authorization: Bearer $SECFEED_KEY" -H "Content-Type: application/json" -d '{...}'

Do MCP requests count against my quota?

Yes, each POST counts as one call, including initialize and tools/list.

curl -X POST "https://secfeedapi.com/mcp" -H "Authorization: Bearer $SECFEED_KEY" -H "Content-Type: application/json" -d '{...}'

Errors

401 when the Authorization header is missing or the key is invalid.
429 when the monthly quota is used.
405 on GET.
400 when the body is not JSON.

Try it with your own key

500 free calls a month.

Get free API key →