MCP troubleshooting
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/<server>. |
| 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, 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). |
| 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. |
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.