> ## Documentation Index > Fetch the complete documentation index at: https://docs.hoppscotch.io/llms.txt > Use this file to discover all available pages before exploring further. # Hoppscotch MCP Server Troubleshooting > Resolve Hoppscotch MCP server errors with this reference of error codes, messages, and causes covering sign-in, request execution, and Cloud limits. Below are the errors the MCP server surfaces, what causes each one, and how to resolve it. How they look depends on your host, which does the presenting, but the message text itself does not change. Some diagnostic output goes to the server's standard error stream rather than into the conversation. If an error is unclear, check your host's MCP server logs. ## The server does not appear in your host **Reason:** The host could not start the server, so no tools are registered and no error reaches the conversation. **Fix:** Work through these in order. 1. Confirm Node.js v22 or higher is on the `PATH` the host uses. A host launched from the desktop may not inherit your shell's `PATH`. 2. Restart the host completely after editing its configuration. Most hosts read MCP configuration only at startup. 3. Run `npx @hoppscotch/mcp-server` in a terminal. It should start and wait. A dependency or Node.js version problem shows up here immediately. 4. Check the host's MCP logs. Startup failures and the configuration warnings below are written to standard error, not to the conversation. ## A tool you expected is missing **Reason:** `HOPPSCOTCH_TOOL_PROFILE` selects which tools exist. The profile gates discovery and execution together, so a tool outside it is invisible to the host and refused even if an agent names it directly. ### Case I **Reason:** The tool is not in your profile. The default is `core`, which excludes team administration and the advanced collection operations. Switching to `standard` removes request execution, code generation, and request CRUD instead. A call to a tool outside your profile is refused with the literal message `Unknown tool: `, which is the same message a tool that does not exist would produce. The message does not tell you which of the two happened. **Fix:** Check [Tools](/documentation/clients/mcp-server/tools) for which profiles include the tool, then set `HOPPSCOTCH_TOOL_PROFILE` accordingly. Use `full` if you need tools from both `core` and `standard`. ### Case II **Reason:** `HOPPSCOTCH_TOOL_PROFILE` is set to a value the server does not recognize. It falls back to `core` and writes a warning to its error output. **Fix:** Check the spelling against `minimal`, `core`, `standard`, and `full`. The warning naming the bad value is in your host's MCP logs. ## `SSRFBlockedError` The target of `execute_request` or `validate_response` was refused before any connection was made. ### Case I > **Blocked request to a private/internal address (``). execute\_request refuses loopback, link-local, cloud-metadata, and private network targets by default. Set HOPPSCOTCH\_ALLOW\_PRIVATE\_HOSTS=true to allow them (e.g. testing a self-hosted or local API).** **Reason:** The URL resolved to an address the guard blocks. This covers loopback, private networks, link-local, carrier-grade NAT, cloud-metadata endpoints such as `169.254.169.254`, and other special-use ranges, across IPv4 and IPv6. **Fix:** If you are deliberately testing a local or self-hosted API, set `HOPPSCOTCH_ALLOW_PRIVATE_HOSTS=true` in your host's `env` block. Setting `HOPPSCOTCH_ALLOW_PRIVATE_HOSTS=true` skips the address checks for **every** `execute_request` and `validate_response` call, not just the one you intended. An agent acting on untrusted input can then reach your internal network and return what it finds into the conversation. Enable it only when you control the input. The restriction to `http` and `https` still applies, and login and backend traffic are unaffected. ### Case II > **Could not resolve `''` to verify it is not an internal address — blocking. Retry if this is a transient DNS error, or set HOPPSCOTCH\_ALLOW\_PRIVATE\_HOSTS=true for intentional local targets.** **Reason:** Name resolution failed, so the guard could not confirm the address is external. It fails closed, meaning it blocks rather than allowing an unverified target. **Fix:** Check the hostname for typos and confirm the machine can resolve it. Retry if the failure was transient. For a hostname that only resolves on your private network, set `HOPPSCOTCH_ALLOW_PRIVATE_HOSTS=true`. ### Case III > **Unsupported URL scheme `''` — only http/https are allowed.** **Reason:** The URL used a scheme other than `http` or `https`, such as `file:` or `ftp:`. **Fix:** Supply an `http` or `https` URL. ## `SecretEgressBlockedError` You set `HOPPSCOTCH_SECRET_ALLOWED_ORIGINS`, and a request referencing a secret environment value targeted an origin that is not on the list. The request was not sent. This error only occurs when `HOPPSCOTCH_SECRET_ALLOWED_ORIGINS` is set. Leaving it unset means no restriction, and secrets substitute into a request to any origin. Each entry must be an absolute origin such as `https://api.example.com`. An entry that does not parse as one, such as a bare `api.example.com`, is **discarded without any warning**. If every entry is discarded the list ends up empty, which refuses secrets to all origins rather than allowing them. Setting the variable to an empty value has the same effect and is the supported way to deny all. ### Case I > **Refusing to substitute secret environment variable(s) {``} into a request to ``: that origin is not allowlisted for secrets. Add it to HOPPSCOTCH\_SECRET\_ALLOWED\_ORIGINS (comma-separated origins).** **Reason:** The target origin was checked before substitution and is not allowlisted. **Fix:** Add the origin to `HOPPSCOTCH_SECRET_ALLOWED_ORIGINS` if it should receive secrets. Otherwise remove the secret reference from the request. ### Case II > **Refusing to send secret environment variable(s) {``}: after substitution the request targets ``, which is not allowlisted for secrets. Check HOPPSCOTCH\_SECRET\_ALLOWED\_ORIGINS.** **Reason:** The URL itself contained a variable, so the final origin was only known after substitution, and that origin is not allowlisted. This second check catches a request whose destination is decided by a variable. **Fix:** Confirm the variable resolves to the origin you expect, then add that origin to the allowlist if it should receive secrets. ## `UnresolvedPlaceholderError` > **Unresolved variable placeholder(s): `{{name}}`. Provide them via the selected environment or remove them; the request was not sent.** **Reason:** You selected an environment, and the request still contained a `{{variable}}` that the environment does not define. The server checks the URL, the header values, and the body. **Fix:** Add the variable to the selected environment, correct the spelling, or remove the reference. This check runs **only when you select an environment**, and only on the URL, the body, and header **values**. With no `environmentId`, an unresolved `{{variable}}` is not an error and goes out on the wire. Select an environment if you want unresolved variables to fail instead. Header names and the `auth` block sit outside both substitution and the check, and they fail differently. Braces are not legal in a header name, so a placeholder there kills the call before anything is sent. In the `auth` block it depends on the type: a bearer token goes out as written, Basic credentials are base64-encoded first, an API key added to the query is percent-encoded into the URL, and an API key whose *name* is a placeholder fails just like a placeholder header name, though only in the default header placement, since a query-placed key is percent-encoded and sent as written. Keep variables in header values or the request body if you want them resolved. ## `ENVIRONMENT_NOT_FOUND` > **Environment `''` not found for this account. Only personal environments are available here; team environments are not.** `execute_request` and `validate_response` read personal environments only. **Reason:** The ID is not one of the signed-in account's personal environments. It may name a team environment, belong to another account, or not exist at all. **Fix:** Pass a personal environment ID, or put the values directly in the request. ## `AUTH_PAT_INVALID` > **Authentication failed. The configured access token looks like a Personal Access Token (pat-...), which only works with Hoppscotch REST API endpoints, not GraphQL queries. Use device-login instead (unset the token), or copy the JWT from `~/.config/hoppscotch-mcp/auth.json`.** **Reason:** `HOPPSCOTCH_ACCESS_TOKEN` was set to a Hoppscotch personal access token. This server talks to the GraphQL API, which personal access tokens cannot authenticate against. **Fix:** Unset `HOPPSCOTCH_ACCESS_TOKEN` and use browser device login, or set it to a JWT copied from the `accessToken` field of `~/.config/hoppscotch-mcp/auth.json`. The server does **not** refuse a `pat-` token up front. It writes a warning to its error output once, then uses the token anyway. This error appears only **after** a request has already been sent and the backend rejected it. Most hosts do not surface that stderr warning, so the first visible sign is usually a failed tool call. ## `MISSING_TEAM_ID` > **Team ID is required. Either provide teamId parameter or set HOPPSCOTCH\_DEFAULT\_TEAM\_ID** **Reason:** A team-scoped tool was called without a team ID, and no default is configured. **Fix:** Set `HOPPSCOTCH_DEFAULT_TEAM_ID` in your host's `env` block, or ask the agent to call `list_teams` first and pass the ID explicitly. ## `COLLECTION_NOT_FOUND` > **User collection `""` not found or not accessible.** **Reason:** The collection ID does not exist, or it belongs to an account other than the signed-in one. **Fix:** Confirm the ID and the signed-in account. Use `reauth` to switch accounts. ## Refusing to write the secret-redaction placeholder > **Refusing to write the secret-redaction placeholder ("`