--- title: MCP troubleshooting description: Every message you might see when using an MCP server through Veefore, what it means, and how to fix it. --- Find the message you see, then follow the fix. Messages from an MCP client appear in the chat or in the client's MCP log; messages from the SDK are in the error it throws; messages in the console appear as a notice at the bottom of the page. After any fix, open **Actions** in the console: every call that reached Veefore is listed there with its decision and the reason. ## Connecting the server | Message | What it means | Fix | | --- | --- | --- | | **The server could not be connected** | Veefore could not reach the URL, or the server did not answer as an MCP server. | Check the URL is the server's MCP address (often ending in `/mcp`), that it is reachable from the internet, and that it uses Streamable HTTP. If it needs a token, enter it under **Access token**. | | **Activate the MCP server before authorizing its tools.** | The server is still *Pending*. | Open the server's page and click **Activate**, or connect it with **Connect server**, which activates it for you. | | **Pick an environment first** | No environment is selected. | Choose one with the **Environment** switcher at the top of the page. | | A password prompt appears | Switching a server on and authorizing tools are protected steps. | Enter your password (or passkey). The step continues where it stopped. | | **You cannot grant capabilities** | Your role lacks `agent:manage_capabilities`. | Ask an admin, or ask them to authorize the tools. | ## From an MCP client | Message | What it means | Fix | | --- | --- | --- | | **Send the agent's MCP key as "Authorization: Bearer vf_mcp_…"** | The client sent no key. | Check the config has the `Authorization` header (or `AUTH_HEADER` for Claude Desktop) and that you restarted the client. | | **This MCP key is not valid. Create a new one in the Veefore console.** | The key is wrong, revoked or expired, or its agent was revoked. | Create a new key on the server's page under **Use this server → MCP client**, paste it in, and restart the client. | | **MCP keys are accepted on the /mcp endpoint only.** | The key was sent to a different Veefore address. | Use the address from **Use this server**: `https://gateway.veefore.com/mcp/`. | | **No MCP server "…" is registered in this agent's environment.** | The server name at the end of the address is wrong, or the server is in a different environment from the agent. | Copy the address from the server's page. Connect the server in the same environment as the agent. | | The client connects but shows **no tools** | No tool on this server is authorized for this agent, or the server is not active. | On the server's page, authorize the tools for this agent (**Authorize** on each tool, or **Connect server** again). | | Claude Desktop shows the server as failed, or `npx` is not found | Node.js is missing, or the config file is not valid JSON. | Install [Node.js](https://nodejs.org), check the file with a JSON validator, and restart Claude Desktop fully. | ## When a call is refused These come back as the tool's answer, so the model can tell you why. In every case **nothing reached the server**. | Message | What it means | Fix | | --- | --- | --- | | **Veefore refused this call: Tool "…" is not on the authorized allowlist for this MCP server.** | The tool was discovered but not authorized. | Authorize it on the server's page, if you want it used. | | **Veefore refused this call: This MCP tool has not been authorized by an operator.** | The same: discovery alone allows nothing. | Authorize it on the server's page. | | **Veefore refused this call: This agent is not on the allowlist for this MCP tool.** | The tool is authorized, but for other agents. | On the tool's **Change authorization**, tick this agent. | | **Veefore refused this call: The MCP server is pending / disabled / quarantined.** | The server is not active. | Activate it on its page. A quarantined server was stopped on purpose; find out why before lifting it. | | **Veefore refused this call: The MCP server rate limit of N/minute was exceeded.** | Too many calls to this server in a minute. | Wait a minute, or raise the limit on the server. | | **Veefore blocked this call: The agent does not hold the capability "…".** | The tool needs a capability the agent does not have. | On the tool's **Change authorization**, tick **Grant … to the ticked agents**, or grant it on the agent's page. | | **Veefore blocked this call: No policy is bound to this scope and the requested capability is classified dangerous.** | The environment is in **Enforce**, there is no active policy, and the tool is high impact. | Add and activate a policy, for example **Starter — safe defaults** (see [Turn on protection](/build/mcp-client#step-by-step)). | | **Veefore blocked this call:** followed by your rule's reason | A rule in your policy refused it. | Open the call in **Actions** to see which rule, then change the rule or the request. | | **The MCP server could not complete this call: …** | Veefore allowed it, but the server returned an error or did not answer. | Check the server is up and the token (if any) is still valid. The call is in **Actions** with the server's error. | ## Approvals | Message | What it means | Fix | | --- | --- | --- | | **This call is waiting for a person to approve it (approval apr_…). Nothing has been done yet.** | A rule requires a person, and no one decided within 20 seconds. | Approve it under **Approvals** in the console, then ask the client to do the same thing again. | | **A person denied this call (approval apr_…). Nothing was done.** | Someone clicked **Deny**. | Ask them why before trying again. | | **The approval for this call is expired** | No one decided in time. | Ask again; a new approval request is opened. | | From the SDK: the call waits a long time | The SDK's default is to wait for the decision. | Use `onApproval: 'defer'` in a chat agent. See [Handle approvals](/build/handle-approvals). | Asking again **with different arguments** opens a new approval: an approval is for exactly one request. ## The call ran when it should have been stopped The environment is in **Observe** mode, which every new account starts in. Calls run and are recorded, and the decision Veefore *would* have made is shown as the shadow decision in **Actions**. Switch to **Enforce** under **Admin → Settings → Gateway enforcement**, or with `veefore deploy --mode ENFORCE`. ## From the CLI | Message | Fix | | --- | --- | | **the installed @veefore/sdk predates mcpServer()** | `npm install @veefore/sdk@1.8.0`, then run `veefore integrate` again. | | A call is listed with **no endpoint URL** | The file does not name the server's URL, or it matches no registered server. Register the server with the exact URL in your code, or make the change by hand. | | `veefore doctor` reports a direct MCP call | Some code still calls the server without Veefore. Reroute it with `veefore integrate` or by hand. | ## Still stuck Open the call in **Actions**: the stages show exactly which check stopped it. If it is not there, the request never reached Veefore — check the address and the key. Then see [Support](/support).