> ## Documentation Index
> Fetch the complete documentation index at: https://docs.secapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect SEC API to LlamaIndex

> Adapt SEC API MCP tools into LlamaIndex FunctionTool objects, verify a filing call, and keep credentials in the server runtime.

Use LlamaIndex when you want hosted SEC API tools as `FunctionTool` objects in
a Python agent or workflow. `BasicMCPClient` uses streamable HTTP for an `/mcp`
URL and accepts a custom `httpx.AsyncClient`, which makes the SEC API header
explicit. Run it in a backend or worker; do not expose the key in a browser
application.

## Make one authenticated filing call

```bash theme={null}
pip install llama-index-tools-mcp httpx
```

Use a process environment variable supplied by your deployment secret manager:

```python theme={null}
import asyncio
import os

import httpx
from llama_index.tools.mcp import BasicMCPClient, McpToolSpec


async def main() -> None:
    async with httpx.AsyncClient(
        headers={"x-api-key": os.environ["SECAPI_API_KEY"]}
    ) as http:
        client = BasicMCPClient("https://api.secapi.ai/mcp", http_client=http)

        # Verify the remote server before giving the tools to an agent.
        result = await client.call_tool(
            "filings.latest", {"ticker": "AAPL", "form": "10-K"}
        )
        print(result)

        tools = await McpToolSpec(client=client).to_tool_list_async()
        print([tool.metadata.name for tool in tools])


asyncio.run(main())
```

The custom `httpx` client is specific to this integration: it supplies the
`x-api-key` header to the streamable HTTP transport. The package also supports
OAuth clients, but an API key is the direct machine-authentication path for the
SEC API endpoint. Do not use its default in-memory OAuth token storage for a
production credential lifecycle.

`BasicMCPClient` and `McpToolSpec` are supplied by
`llama-index-tools-mcp`; check its [package release notes](https://github.com/run-llama/llama_index/releases)
when upgrading because its MCP client API evolves independently of SEC API.

## Turn the verified tools into a workflow

Pass `tools` to a LlamaIndex `FunctionAgent` or workflow only after the direct
call returns the expected filing. Build the tool list during application startup
or another controlled lifecycle boundary; refresh it after an integration
upgrade instead of relying on a stale local schema. Limit the agent's first
calls by issuer, filing form, period, and result count.

## Keep filing identity in workflow state

The filing result identifies the underlying record with `accessionNumber`,
`filingDate`, and `filingUrl`, plus `requestId` and `traceparent` for request
diagnostics. Save those fields in the workflow state and user-visible answer.
When other tools return provenance, freshness, or source data, retain it with
the conclusion so a reader can inspect the filing rather than trust a generated
summary alone.

## Errors and limits

Treat SEC API failures as tool results to classify, not as a reason for an
unbounded agent loop. Fix `401`; resolve `402`; honor `Retry-After` on `429` or
a temporary `503`; and narrow a request after `mcp_tool_timeout`. Keep the
JSON-RPC error, `error.data.code`, and request ID for repeatable failures.

## Next step

Connect the verified `FunctionTool` list to your agent and make accession
number, filing URL, and request metadata required output for filing analysis.