*MCP › Guides*

# Troubleshooting

> Most problems are the URL, the scopes or a client that keeps an old list of tools.

## The client says it is not authorized

A call without a credential gets an HTTP 401 with a problem body and a `WWW-Authenticate` header that points to the OAuth metadata. A client with OAuth starts the sign-in; one with a key needs the header. With a key, the code says why: [`api_key_invalid`](https://docs.filmo.io/rest-api/errors/api_key_invalid), [`api_key_revoked`](https://docs.filmo.io/rest-api/errors/api_key_revoked), [`api_key_expired`](https://docs.filmo.io/rest-api/errors/api_key_expired), [`api_key_owner_inactive`](https://docs.filmo.io/rest-api/errors/api_key_owner_inactive) or [`api_key_owner_not_admin`](https://docs.filmo.io/rest-api/errors/api_key_owner_not_admin).

## The URL is not the right one

The only URL is `https://app.filmo.io/api/v1/mcp`. Another production host answers with a redirect (308) and, for a client that does not follow it on a POST, a JSON-RPC error that names this URL. A client that follows the redirect drops the `Authorization` header when the origin changes, so sign-in fails in a way that looks like a bad key. Type the URL exactly as shown.

## A tool is missing

- With a key, the catalogue lists only what the key can call: check its scopes against the tool's scope on its page. It also leaves out the tools whose add-on the account lacks (an account in trial has them all).
- With OAuth, a client is not guaranteed to list the tools again after you consent. Start a new conversation after you connect.
- A tool that needs an add-on the account lacks is not listed; calling it anyway returns [`addon_required`](https://docs.filmo.io/rest-api/errors/addon_required). See [Plans and add-ons](https://docs.filmo.io/concepts/plans-and-add-ons).
- The client may be over its tool limit and drop tools. Use a preset: see [Limits and context](https://docs.filmo.io/mcp/guides/limits-and-context).

## A scope is not checked or a call says insufficient scope

Writes, `workflows:run` and `ai:ask` start unchecked in the consent screen, even if the client asked for them. Check them by hand if the assistant needs them. To change scopes after you connected, remove the connector and add it again.

## I did not start this consent

Do not approve it. Read [Before you approve](https://docs.filmo.io/mcp/authentication#before-you-approve).

## A call takes too long or times out

[`filmo_ai_ask`](https://docs.filmo.io/mcp/tools/ai/filmo-ai-ask) can take tens of seconds. Raise the client's timeout, or ask a narrower question. Lists with many rows take longer to return and to read: ask for `limit` 20.

## Too many requests

[`rate_limited`](https://docs.filmo.io/rest-api/errors/rate_limited): wait `retryAfter` seconds. The availability tools share a separate quota of 30 calls a minute.

## OAuth does not work on a server or in a container

Clients that open a browser for the sign-in (Claude Code, Codex, Gemini CLI) need one. On a machine without a browser, use an API key kept in the environment.

## A key leaked

Revoke it in the API and MCP page of the app's settings and create another with the same scopes. A revoked key stops working at once. Then check what it did. [Security](https://docs.filmo.io/further-reading/security#leaked-key) has the full procedure.

## Asking for help

Give the `requestId` of the problem, the tool and the time. Never send the key.

---

Canonical URL: https://docs.filmo.io/mcp/guides/troubleshooting  
Last updated: 2026-10-25