> ## 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 Windsurf

> Add the SEC API streamable HTTP MCP server to Windsurf Cascade, keep the key out of the JSON file, and verify a cited filing lookup.

Use Windsurf Cascade for a developer-owned MCP session. It reads remote MCP
servers from its global JSON configuration and supports streamable HTTP,
custom headers, and environment-variable interpolation. This is a local setup,
not a way to distribute a production credential to a team or an application.

## Add a local development key

Export a development key before launching Windsurf:

```bash theme={null}
export SECAPI_API_KEY="your-development-key"
```

Open **Windsurf Settings > Cascade > MCP Servers**, choose **View Raw Config**,
and add SEC API to `~/.codeium/windsurf/mcp_config.json`:

```json theme={null}
{
  "mcpServers": {
    "secapi": {
      "serverUrl": "https://api.secapi.ai/mcp",
      "headers": {
        "x-api-key": "${env:SECAPI_API_KEY}"
      }
    }
  }
}
```

Keep an existing `mcpServers` object and add only the `secapi` entry. Windsurf
supports both `serverUrl` and `url` for a remote HTTP MCP; this example uses the
documented `serverUrl` form. Restart Windsurf if its process cannot see the
exported variable, then refresh the MCP list in Cascade.

Windsurf's [MCP documentation](https://docs.windsurf.com/windsurf/cascade/mcp)
is the source for its configuration path and environment interpolation behavior.

## Prove one cited filing lookup

In Cascade, ask:

> Call `filings.latest` with `ticker: AAPL` and `form: 10-K`. Return the
> accession number, filing date, filing URL, `requestId`, and `traceparent`.

The filing URL and accession number are the evidence trail for the response.
Preserve them, along with request metadata, in generated code, a research note,
or a handoff. For search and extraction tools, preserve returned provenance and
freshness fields rather than reporting an uncited conclusion.

## Lifecycle and scope

Windsurf loads MCP tools from the configured server; refresh the MCP panel after
editing the file and review which tools are enabled before a broad task. Cascade
has a finite available-tool budget, so enable the SEC API tools needed for the
workflow and constrain early calls by issuer, form, date, and result count.

For a deployed service, do not copy this JSON into the application or expose its
key to a web client. Make the MCP connection from server-side code and load the
key from that runtime's secret manager.

## Failures and limits

* `401` normally means the environment variable was unavailable to Windsurf or
  the key was rejected.
* `402` requires an account, credit, or budget action rather than a retry.
* On `429` or temporary `503`, follow `Retry-After` and lower parallel work.
* On `mcp_tool_timeout`, reduce the query scope before one bounded retry.

Keep the JSON-RPC error, `error.data.code`, and `requestId` for repeated
failures. See [Request diagnostics](/request-diagnostics) for a safe diagnostic
record.

## Next step

After the filing lookup works, ask Cascade to use the filing URL and accession
number as required output fields for every SEC API-backed conclusion.