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

# Troubleshoot MCP

> Resolve connection, authentication, operation-discovery, and account-scope errors.

Start with the failing step: connection, specification discovery, or the Straddle request. Each checks a different part of the setup.

## The server is missing or disconnected

Check the server address in your client's MCP settings:

| Server | Address |
| - | - |
| `straddle-docs` | `https://straddle-build-straddle-openapi.apidocumentation.com/mcp` |
| `straddle-api` | `https://mcp.scalar.com/mcp/d5d1b1c2-ae5b-432d-b795-4fcb31cfdedd` |

Use the [connection instructions](/developer-tools/mcp/install) for your client, then restart the connection. In Claude Code, inspect `/mcp`. In Codex, run `codex mcp list --json`. In Cursor, check **Customize**; in VS Code, use **MCP: List Servers**.

If the URL is correct, inspect the client's MCP output for connection errors and confirm your network can reach that hosted address.

## Discovery succeeds but the request returns 401

Specification discovery checks the contract, so it can succeed without a valid API key. For a `401`, check the following:

1. Supply `STRADDLE_API_KEY` to the process that starts your client.
2. Confirm the key belongs to the same environment as `serverBaseUrl`.
3. Restart the client or MCP connection after changing the credential.

For Codex, confirm `bearer_token_env_var` is `STRADDLE_API_KEY`. For Claude Code, the header must keep the literal variable reference shown in [Connect MCP](/developer-tools/mcp/install). For the Cursor plugin, check its **Configure** credential field.

## The request returns 403 or 404

For `403`, check whether the key can use the operation and selected account. For `404`, confirm the resource ID and environment, then review the [account header rule](/developer-tools/mcp/account-scoping).

Use the resource's exact ID from the same environment. Keep the method, path, HTTP status, and request ID from the failure so the next investigation has concrete evidence.

## Scalar cannot find the operation

“Failed to get operation” points to the operation ID. “Does not belong to the given document version” points to the document and operation pair.

Repeat `search-openapi-operations` in the current session. Use `x-scalar-document-version-id` and the matching operation's `x-scalar-operation-id` from that result. The OpenAPI name, such as `getAccount`, is not the Scalar operation ID.

Then rebuild the request with those IDs. See [API requests](/developer-tools/mcp/api-requests).

## The request targets the wrong environment

Inspect `serverBaseUrl` in the tool request. Set it to the resolved host, such as `https://sandbox.straddle.com`.

Set the account in the MCP request separately from the CLI's selected account. Include the header when the [operation requires it](/developer-tools/mcp/account-scoping).

## Docs MCP lists API execution tools

Use Docs MCP's `search-documentation` tool for documentation. Send API tasks through `straddle-api`, where the client is configured with your Straddle key.

The hosted server controls its tool list. Check the server URL to confirm which connection supplied the tools.

## Prepare an error report

Include the client version, server name, tool name, method and path, environment, HTTP status, and request ID when available. Describe what you expected and what happened. Remove API keys, paykey tokens, and personal data before sharing the report.


## Related topics

- [Troubleshoot Straddle skills](/developer-tools/skills/troubleshooting.md)
- [Troubleshoot the Straddle CLI](/developer-tools/cli/troubleshooting.md)
- [Connect MCP](/developer-tools/mcp/install.md)
- [Read an account through API MCP](/developer-tools/mcp/api-requests.md)
- [Connect your agent to Straddle](/developer-tools/mcp/overview.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.