Skip to main content

​
Hosted MCP Workflows

Hosted MCP lets coding agents call SEC API directly from MCP-aware tools. Use it when you want agents to resolve issuers, fetch filings, extract sections, and run intelligence workflows without writing a custom integration first.

​
Why Use Hosted MCP

Less wrapper code

Your agent can call SEC API tools directly from its MCP client.

Same workflows

REST and hosted MCP sit on top of the same underlying SEC API workflows.

Faster setup

A working MCP install gets you to a useful issuer, filing, or section workflow quickly.

​
Install Metadata

curl https://api.secapi.ai/mcp
That payload includes:
  • the canonical streamable HTTP MCP transport URL
  • auth metadata links
  • sponsored bootstrap URLs for human token issuance and machine bootstrap
  • install hints
  • current tool and resource summaries
1

Fetch the install metadata

Confirm the hosted MCP endpoint is live and returning its transport and auth metadata.
2

Set the API key

Export SECAPI_API_KEY or configure the same value as an x-api-key header in your MCP client.
3

Register the server in your client

Add the streamable HTTP MCP endpoint to Claude Code, Cursor, or another MCP-aware client.
4

Exercise a real tool path

Resolve an issuer, fetch a filing, and extract a section before using the server in production workflows.

​
Common clients

​
Claude Code

claude mcp add --transport streamable-http sec-api https://api.secapi.ai/mcp \
  --header "x-api-key: $SECAPI_API_KEY"

​
Cursor

{
  "sec-api": {
    "url": "https://api.secapi.ai/mcp",
    "headers": {
      "x-api-key": "${SECAPI_API_KEY}"
    }
  }
}

​
Good first tools

  • entities.resolve
  • filings.search
  • filings.latest
  • sections.get
  • statements.get
  • market.snapshots
  • macro.indicators
  • factors.returns
  • factors.history
  • factors.sparklines
  • factors.extreme_moves
  • factors.extreme_pairs
  • factors.valuations
  • factors.valuation_stocks
  • portfolio.analyze
  • portfolio.attribution
  • portfolio.hedge
  • intelligence.query

​
AI query quota

MCP tools/call requests for intelligence.query and signals.dilution.enhanced.get count toward the monthly ai_queries quota. Successful calls include a top-level _secapi.quota envelope with projected post-call usage: 
{
  "jsonrpc": "2.0",
  "id": "quota_example",
  "result": {},
  "_secapi": {
    "quota": {
      "family": "ai_queries",
      "mcpToolName": "intelligence.query",
      "limit": 600,
      "used": 42,
      "remaining": 558,
      "resetAt": "2026-05-01T00:00:00.000Z"
    }
  }
}
When the quota is exhausted, hosted MCP returns HTTP 429 with JSON-RPC error data such as code: "ai_query_quota_exceeded". Treat quota exhaustion as non-retryable until reset or plan upgrade. If a tool circuit is open, retry only after availability backoff.

Copy this SEC API prompt for your agent.

​
Example tool call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "intelligence.query",
    "arguments": {
      "query": "Decompose AAPL's last 6M return into factors, identify unusual factor moves, then suggest hedges.",
      "entities": ["AAPL"],
      "lookback": "6m",
      "responseMode": "compact_json_and_md"
    }
  }
}