Troubleshooting

Running into issues? This page covers the most common problems and how to resolve them.

"No spec found" error

This means FlashMCP's discovery engine couldn't automatically locate an OpenAPI spec for the target API. This can happen when the API doesn't publish its spec at a discoverable location.

Solutions

• Use ?spec= to provide the spec path directly. Check the API's documentation for a link to their OpenAPI or Swagger spec file.
• Verify the API actually publishes an OpenAPI spec. Not all APIs have one — FlashMCP requires an OpenAPI 3.x or Swagger 2.0 spec to generate tools.
• Try an absolute URL if the spec is hosted on a different domain (this is common for major APIs).

{
  "mcpServers": {
    "my-api": {
      // Relative path (spec on same domain)
      "url": "https://flashmcp.dev/api.example.com?spec=/openapi.json"
    }
  }
}

{
  "mcpServers": {
    "my-api": {
      // Absolute URL (spec on different domain)
      "url": "https://flashmcp.dev/api.example.com?spec=https://docs.example.com/openapi.json"
    }
  }
}

"Authentication failed" or 401/403 errors

These errors indicate that your API credentials aren't being forwarded correctly to the upstream API. FlashMCP passes through Authorization, X-API-Key, and any X-* headers from your MCP client to the target API.

Things to check

• Ensure headers are configured in your MCP client. Each client has its own syntax for setting custom headers — consult your client's documentation.
• Verify the header names match what the API expects. Some APIs use Authorization: Bearer <token>, others use X-API-Key, and some use custom headers.
• Check that tokens haven't expired. If you're using OAuth tokens, they may need to be refreshed.
• Confirm the credentials have the right permissions. Some API keys are scoped to specific operations — make sure yours covers the endpoints you're trying to access.

{
  "mcpServers": {
    "my-api": {
      "url": "https://flashmcp.dev/api.example.com",
      "headers": {
        "Authorization": "Bearer your-api-token-here"
      }
    }
  }
}

"Connection timeout" or "API unreachable"

This means FlashMCP was unable to reach the target API. The issue is between FlashMCP's edge network and the upstream API server.

Things to check

• Verify the API hostname is correct. Typos in the domain name are a common cause — double-check the URL in your config.
• Check if the API is currently down. Visit the API's status page or try reaching it directly from your browser.
• VPN or IP allowlisting. Some private APIs restrict access by IP address. FlashMCP makes requests from its edge network, which may not be in your allowlist.
• Firewall rules. Corporate firewalls may block outbound connections to FlashMCP. Ensure flashmcp.dev is not blocked.

"Tool not found" error

This error occurs when your LLM tries to call a tool name that doesn't match any tool generated from the API spec.

Things to check

• Use tools/list to see all available tools. This shows the exact tool names FlashMCP generated from the spec.
• Tool names come from the spec. If the API defines an operationId, that becomes the tool name. If not, FlashMCP auto-generates names from the HTTP method and path (e.g., get_pets, post_pets).
• The spec may have changed. If the API recently removed an endpoint, the tool will no longer exist. Cached specs refresh automatically, so this should resolve on its own.

Large API pagination

FlashMCP returns tools in pages of 50. If the target API has hundreds of endpoints, you may only see a subset of the tools at first.

How it works

• The tools/list response includes a nextCursor field when there are more tools available.
• Your MCP client should automatically follow cursors to fetch all pages. Most modern MCP clients handle this transparently.
• If you're only seeing 50 tools from a large API, your MCP client may not support cursor-based pagination — check your client's MCP protocol version compatibility.

Request body not being sent

If your API call seems to be missing the request body, the most common cause is nesting parameters incorrectly.

The fix

FlashMCP flattens request body parameters into the tool's top-level input schema. This means you should pass parameters directly — not wrapped in a body object.

// Correct — pass parameters at the top level
createPet({ name: "Rex", status: "available" })

// Avoid — nested body wrapper is unnecessary
createPet({ body: { name: "Rex", status: "available" } })

FlashMCP does support the legacy body wrapper for backward compatibility, but flat parameters are preferred and more reliable.

Getting help

If you're still stuck after trying the solutions above, reach out to us and we'll help you get connected.

• Email: support@flashmcp.dev

When contacting support, please include:

• The API hostname you're trying to connect to
• The MCP client you're using (Claude Desktop, Cursor, etc.)
• The full error message or unexpected behavior you're seeing
• Your FlashMCP URL (with any ?spec= parameter, but redact credentials)