Troubleshooting

Work down this page in order — the checks are cheapest first.

The server returns 404, or the client says it cannot be found

Three causes, in the order worth checking.

On a self-hosted instance, the endpoint is off by default. Set MCP_ENABLED=true in .env, then restart. If you cache configuration, run php artisan config:clear first — otherwise the old value stays live and nothing appears to change. See Self-hosted instances. When disabled, this covers the OAuth endpoints too, not just /mcp itself, so authorization will also 404 rather than fail with an auth error.

The URL is wrong. It must be your own instance’s hostname with /mcp on the end, and no /api/v1 in the path:

https://your-instance.pentestpad.com/mcp

A wrong hostname produces exactly the same 404 as a disabled endpoint, so confirm the host loads in a browser.

You are on PentestPad Cloud and still get 404. The endpoint is enabled by default there, so this points at the URL rather than at configuration. Check for a typo in the subdomain.

The browser flow does not complete

You click Authorize, or the tab opens, but the client never reports success.

• The client and the browser must be reachable from each other. The authorization flow finishes with a redirect back to a loopback address the client is listening on. If your MCP client runs somewhere the browser cannot reach — inside a container, over SSH to a remote machine, on a headless server — that redirect has nowhere to land. Run the client on the machine whose browser you are approving in.
• Check for a blocked pop-up or a proxy intercepting localhost. Some corporate networks or browser extensions block loopback redirects. Try a different browser or temporarily disable the extension.
• Retry from a clean state. Remove and re-add the server (claude mcp remove pentestpad then the claude mcp add command again) rather than repeating the same stuck attempt.

Connected to the wrong tenant’s domain

Each PentestPad instance — your company’s subdomain — has entirely separate accounts, authorized applications, and tokens. Approving the consent screen on the wrong domain authorizes access to that instance only, not the one you meant to use.

Check the hostname in your claude mcp add command or mcp.json against the instance URL you actually use to sign in day to day. If you approved the wrong one, disconnect it from that instance’s Profile → API Access and reconnect at the correct domain.

401 Unauthorized

The client has no valid token for your account. This is usually not something you did — the client manages the OAuth token itself — but a few things invalidate it:

• You disconnected the application. Check Profile → API Access on the instance you are connecting to. If it is not listed under Connected applications, it was revoked and needs to go through the browser approval again.
• The stored token expired and the client’s automatic refresh failed. This can happen if the client has not been used in a long time. Remove and re-add the server so it starts a fresh authorization.
• You are pointed at the wrong tenant’s domain — see above.
• The instance runs several containers with mismatched signing keys. Self-hosted only. If the deployment was scaled past one container without setting shared signing keys, tokens are valid only on the container that issued them, so requests fail whenever they land elsewhere — which looks like an intermittent 401 rather than a configuration problem. See Running more than one container.

“Authorization unavailable” when connecting

You reach the sign-in and consent step, but instead of a normal consent screen PentestPad shows Authorization unavailable and explains that the endpoint is available to team members only.

Your account is a client-role account. Client users cannot use the MCP endpoint in the current release — see Who can connect. This is enforced at the authorization screen itself, not a setting you can change, and it holds even if a token was somehow issued before — every call still fails. Your REST API access is unaffected.

Connected, but no tools appear

The handshake succeeded and the tool list came back empty, or the client shows nothing.

• Restart the client. Most MCP clients cache the tool list from the first successful handshake.
• Re-run claude mcp list and check the server reports as connected rather than failed.
• Confirm you are not looking at a different server with a similar name. If you also have entries from Settings → MCP Servers in play, those are an unrelated feature.

The assistant says it cannot find a project or finding

Usually correct rather than broken. The tools only ever see what your account can see, so a project you are not a member of does not exist as far as the assistant is concerned. Open it in the web UI to confirm you have access.

Archived projects are invisible to every tool. Restore the project first if you need to work on it.

“Unknown status slug”

set-project-status only accepts slugs that exist in your instance, and those are defined per instance rather than fixed. Ask the assistant to list the available statuses first, or check the project status settings in the admin panel.

Rate limited (429)

The limit is 120 requests per minute per user. Reaching it usually means an assistant is looping — retrying a failing call instead of stopping. Wait a minute and start a fresh conversation rather than continuing the one that stalled.

A write may or may not have gone through

If a tool reports an internal error and says the outcome is unknown, take it literally and do not ask the assistant to retry. Open the record in the web UI and check. Retrying is how the same finding gets filed twice.

Still stuck

Email support@pentestpad.com with your instance URL, the client you are using, and the exact error text. Never include an access token, refresh token, or authorization code in the email.