Common Errors

New server not showing up in AI client

Symptom: you installed a server in MCPFirewall but your AI client does not see it.

Fix: restart your AI client. AI clients load their MCP server list at startup. New servers, removed servers, and configuration changes are not picked up until the client restarts. Close the client fully and reopen it.

MCPFirewall shows a yellow restart banner on the Integrations page when clients need restarting. This is by far the most common issue new users hit.

Gateway not running

Symptom: mcpfw status reports “not running”, shims fail to connect, dashboard unreachable.

Fix: start the gateway with mcpfw serve or mcpfw service start. If it was running and stopped unexpectedly, check the logs:

mcpfw service logs --n 50

Port already in use

Symptom: mcpfw serve fails with “address already in use”.

Fix: another process is using port 8765. Find it and stop it, or use a different port:

mcpfw serve --port 9000

Tools invisible to AI

Symptom: the AI client does not see tools from a server that should be available.

Causes (check in this order):

1. Tool is Disabled: disabled tools are filtered from the tools/list response. Check the tool’s mode on the MCP Hub page.
2. Lockdown active: if Lockdown mode is on (red indicator in sidebar), all tools are invisible. Clear it from the sidebar.
3. Wrong ruleset: the tool may be enabled in one ruleset but disabled in the one that is actually active. Check the ruleset resolution order.
4. Server not protected: if the server is not routed through the gateway, MCPFirewall has no control over it. Check the MCP Hub for “Discovered, Not Protected” servers.

Approval requests timing out

Symptom: tool calls that require approval are automatically denied before you can respond.

Fix: increase the timeout in Settings > Approval timeout. Enable OS notifications so you are alerted immediately. If you are regularly missing approvals, consider switching frequently-used tools to “Enabled” and keeping “Requires Approval” only for high-risk operations.

OAuth token expired

Symptom: an MCP server stops working, the Vault page shows a red expiry indicator.

Fix: click Re-authorize on the token in the Vault page. This starts a new OAuth flow. If automatic refresh should have worked but did not, the refresh token may have also expired (some providers expire refresh tokens after 30-90 days).

From the CLI:

mcpfw oauth revoke <server-name>

Then re-authorize from the dashboard or the Discover page.

Secrets not injected

Symptom: a server fails to start with “missing environment variable” errors even though the secret exists in the vault.

Check:

1. The config uses the correct reference format: $MCPFW_SECRET:secret_name
2. The secret name matches exactly (names are case-sensitive)
3. The secret exists in the vault (check the Vault page)

Server shows disconnected

Symptom: a server card on the MCP Hub shows a disconnected status.

Check the server log:

mcpfw logs <server-name>

Common causes:

• The server binary was moved, deleted, or not installed
• A required environment variable or credential is missing
• For HTTP servers: the upstream URL is unreachable

Run a probe from the server card to get a diagnostic report.

Running diagnostics

If you are stuck, run the full diagnostic check:

mcpfw doctor

This checks the gateway, database, vault key, server registrations, and client configurations. Add --json for machine-readable output you can share when asking for help.