Skip to main content

Troubleshooting

Connection issues​

My MCP client can't connect to apistash​

  1. Check the URL. The correct endpoint is https://api.apistash.io/mcp — note both the https:// scheme and the /mcp path suffix. The bare domain without the path is the REST API, not the MCP endpoint, so your client will not find a server there.

    Use https://, not http://. A plain-HTTP request is redirected to HTTPS, and while the redirect preserves your request, your API key has already crossed the network unencrypted — treat any key you sent over http:// as compromised and replace it.

  2. Check the transport type. apistash uses Streamable HTTP, not the older HTTP+SSE transport or stdio. Make sure your client is configured for Streamable HTTP.

  3. Check your API key (if using one). Keys are shown only once at creation time. If you lost it, revoke it and generate a new one from the dashboard.

  4. Check for network/firewall issues. Try a direct curl to verify reachability:

    curl -s https://api.apistash.io/health
    # Expected: {"status":"healthy"}

My client connects but shows no tools​

An authenticated connection advertises setup, bootstrap, and agent_context. If those three are missing too, reload the client and verify that it is authenticated against the correct endpoint. If only your ordinary tools are missing, sign in at app.apistash.io, open Settings → MCP Settings, select the tools you want your agents to have, and save.

This is deliberate rather than a default gone wrong: a tool list is sent to the model on every session, so shipping the whole catalogue to every agent would cost context and blur the model's tool choice. You pick what each agent needs. See the access model.

Also check the key's MCP capabilities: each governed category must be granted explicitly. For ordinary tools, open the key's detail page and confirm Tools is granted. Without it, only the three system tools remain. The same category rule applies to Resources, Prompts, and Agents. Agents governs Agent-definition use rather than a fourth native protocol list.

Working in an organization? The selection lives under the organization's own Settings → MCP Settings. A governed platform tool must also be designated organization-wide or admitted by at least one of the credential's bound teams — see below.

Tools don't appear in my client​

  • Check your tool selection first — see above; an empty selection is the most common cause.
  • Restart or reload your MCP client after updating the configuration. Most clients do not hot-reload the server list.
  • Verify the server entry is in the correct section of your client's native configuration. Claude Desktop's remote connection appears under Customize → Connectors instead of a local mcpServers file.

I asked my agent to set up apistash, but it did not install anything​

setup is only called when you explicitly ask to set up, install, repair, or update apistash. It is not an automatic task-start action. Both setup and bootstrap are authenticated system tools; they do not need Tools / mcp_tools or a tool-policy entry. If they do not appear, reload the client and verify its authentication and endpoint configuration.

The agent installs the returned instruction through the current client's own persistent-instruction mechanism. If more than one file, target, or scope could apply, it should ask you which one to use. If the client has no writable persistent-instruction mechanism, the agent should show the canonical instruction and report not_installed rather than claiming success.

Claude Desktop's native project instructions are edited through Set project instructions; a normal MCP call cannot change that UI setting. In that client, not_installed is the correct agent result: paste the shown managed block into the intended project and verify it there. For Cursor, Windsurf's legacy Cascade agent, OpenCode, Cline, Continue, Gemini CLI, and custom SDK hosts, use the current native target and verification step in Set up task-start context.

Never paste a key, token, or client secret into the setup message. If the agent proposes a global file when this apistash connection is project-specific, or more than one native target is already in use, choose the intended scope before approving a write.

To repair or update an existing installation, ask the agent to set up apistash again. It updates only the apistash-managed instruction when the version is older, leaves a same or newer version unchanged, and preserves unrelated instructions. See setup.

If setup succeeds but a later task cannot call Bootstrap, it must not retry automatically. Report blocked delegated role requirements and continue only work independent of them.

Guided setup is only partially complete​

The agent should account for every confirmed item as created, updated/unchanged, skipped, or blocked. Installing task-start instructions does not prove that starter content was created or assigned. Ask for the exact blocked operation and target, the returned safe error code if any, and the next action that is known.

  • A missing management tool means the operation is unavailable to this Connection. Its absence does not identify a particular hidden policy. Review configured Tools access, tool selection, and applicable policies in the dashboard; native Prompts and Resources have separate access.
  • A known capability_denied or false create flag should be reported as that specific limitation. tool_not_permitted does not reveal which policy excluded the tool. A forbidden action must not be replaced by a guessed policy diagnosis. Plan capacity and validation errors are separate.
  • Without required management reads, updates needing the raw Prompt template/arguments or Resource content/version remain blocked, even if native reads and update tools work. Do not guess those inputs or create a duplicate automatically.
  • Successfully stored Resources can still be absent from MCP discovery. Check the Resource's exposure and this Connection's Resources access in the dashboard. Missing discovery alone does not establish the cause. Do not recreate or automatically enable a saved Resource.
  • Agent assignment, organization-catalogue publication, and connector secrets remain separate dashboard actions. Creation does not assign an Agent or publish Team content organization-wide.

After the relevant access or limit is corrected, verify the specific pending item. Do not retry an unchanged denied request. A confirmed storage-only Resource can complete without read access; otherwise intended but unverified MCP use remains pending. See the management workflow.

My Agent behavior or conditional context was not loaded​

First check the Bootstrap arguments: primary_agent is required. A primary normally sends {"primary_agent":true}; a subagent must also specify its parent's agent_selection. named requires the exact agent name, self permits delegated self-selection, and none deliberately loads no role. Empty arguments return invalid_params.

Then check Agents (agents for API keys, mcp_agents for OAuth). Without it, calls without a name return base context with disabled role and catalog states; named selection and agent_context return capability_denied. Tools does not grant Agents.

An unavailable credential assignment returns agent.status: assignment_unavailable, without its identity or a hidden reason. Report it and ask for direction rather than selecting a replacement automatically. In contrast, an unassigned primary receives selection_available and may choose a suitable role. An explicit unavailable name returns method_not_found; it never falls back to the assignment.

A catalog with status: not_requested is not empty: a named or none subagent can request it with request_agent_catalog: true, keeping its role arguments unchanged. An available catalog with agents: [] really has no visible entries. A self subagent with no suitable definition reports to its parent and awaits a decision; it does not proceed roleless automatically. See Bootstrap.

agent_context resolves the submitted name to its current active definition. If a name or conditional component changes, it returns the non-revealing agent_context_unavailable result without partial content. Bootstrap again with the same role selection before deciding whether to retry with the current definition. See conditional context.

My custom tools, prompts, or resources don't appear​

  • Authenticate. MCP requires an API key or OAuth token — without one, requests are rejected with 401. Make sure your client is sending the credential.
  • Check the credential's MCP capabilities. Every key exposes only the selected governed categories — tools, resources, prompts, and/or agents. Leaving the selection empty grants no governed native surface or Agent-definition use; the three authenticated system tools remain available.
  • Check the access model. A credential only uses the categories it was granted, the built-in tools on its allowlist, and the items its ownership and team bindings reach. See the access model.

Authentication errors​

I get a 401 Unauthorized response​

  • The API key may be invalid or revoked. Check the dashboard to confirm the key is active.
  • Ensure your API key is in the X-API-Key header: X-API-Key: YOUR_API_KEY. (An OAuth token instead goes in Authorization: Bearer <token> — an API key sent as a Bearer token is rejected.)

I get a 404 Not Found with an organization credential​

For a user credential scoped to an organization, this response can mean the acting user is no longer a member. Check the organization selected by the credential and ask an administrator to verify membership, or reconnect with a credential for a context you can access.

I get a 403 Forbidden on the MCP endpoint even though I'm signed in​

The MCP endpoint (POST /mcp) does not accept dashboard JWTs or session cookies. Only API keys and OAuth tokens are valid on this endpoint.

Sign in to the dashboard and generate an API key, then send it in the X-API-Key: YOUR_API_KEY header in your MCP client configuration. See Authentication.

A tool call returns tool_not_permitted​

MCP returns this policy denial as a tool result with isError: true and structuredContent.error.code: "tool_not_permitted". It does not identify which policy excluded the tool. Check the applicable layers in the dashboard:

  • The platform-tool allowlist. Under Settings → MCP Settings, the personal account or organization must select the governed platform tool. A key or team policy cannot admit a platform tool missing from that selection.
  • A standalone personal key's Tool policy. If it uses a whitelist, include the tool; if it uses a blacklist, remove the tool from that blacklist. Keep the policy limited to what the agent needs.
  • Organization-wide and team admission. In an organization, an allowlisted platform tool must also be designated organization-wide or admitted by at least one bound team's Tool policy. Without team bindings, only the organization-wide selection provides this admission. Ask an administrator to review the designation, team bindings, and team policies as appropriate.

Missing Tools capability instead returns capability_denied. Unknown or deprecated platform tools return the neutral protocol error method_not_found. See the access model for customer content and other credentials.

Creating an API key returns 409 Conflict​

You already have an active key with that name. Key names must be unique across your active keys. Choose a different name or revoke the existing key from the dashboard first.

I registered but can't log in — "Email address not verified"​

You must verify your email address before you can sign in. After registration, apistash sends a verification email — click the link inside it to activate your account, then try logging in again.

  • Check your spam folder if the email hasn't arrived after a few minutes.
  • Verification links expire after 24 hours. If your link has expired, go back to the login page and use the "Resend verification email" link to request a fresh one.
  • This restriction does not apply to OAuth sign-ins (e.g. Google) — those accounts are verified automatically.

Registration or password reset fails with "service unavailable"​

Sign-up, password reset and "resend verification email" refuse to run when email delivery is temporarily unavailable, rather than half-completing. You get a 503 and nothing was changed — no account was created, no reset link was consumed, no cooldown was started. Wait a moment and repeat the request.

My token expired mid-session​

Dashboard access tokens are short-lived (15 minutes). Clients that use the REST API directly should refresh them with POST /api/auth/refresh; those dashboard tokens are never valid on MCP. An MCP client may instead use a long-lived API key or its own OAuth access/refresh-token flow. An OAuth-capable MCP client must refresh its OAuth token according to the discovered authorization server metadata.

Rate limiting​

A tool call or content read is rate-limited​

An MCP tool call returns isError: true with structuredContent.error.code: "rate_limited". A native prompt or resource read returns the protocol error invalid_params with data.code: "rate_limited". In both cases, the error's details include the violated window and retry_after_seconds; do not rely on an HTTP 429 status to detect these MCP limits.

  • Back off and retry — honour the retry delay in the error rather than retrying immediately.
  • Reduce request frequency — add delays between tool calls in your agent, or batch work so it makes fewer calls.
  • Review your limits — see Plans & Limits for the current allowances and plan availability.

Rate limits are shared per personal account or organization, not per API key. Calls from a member's personal space within an organization share that organization's rate-limit windows. Issuing another key does not raise them. Fetching prompts and reading resources uses separate read limits from tool calls.

Tool errors​

Tool failures use two response forms:

  • Tool error (isError) — a well-formed call whose operation failed (a rejected value, a plan limit, a permission denial, a throttle). The response is a normal tool result with isError: true and the machine-readable code in structuredContent.error.code (plus a human message and, where useful, details). Your agent can read the code and self-correct.
  • Protocol error — a JSON-RPC error: invalid_params (your arguments don't match the tool's input schema), method_not_found (the tool or item isn't available to you), or internal_error (an unexpected server error). For tool argument errors, invalid_params includes the precise code in data. method_not_found and internal_error intentionally omit data to avoid exposing unavailable items or internal details.

Each tool's reference page lists its exact codes and how each is delivered.

The calculator returns an error for my expression​

  • Check that the expression uses supported syntax (see the calculator reference)
  • Division by zero, undefined results, and unsupported functions (e.g. factorial) come back as a tool error with isError: true and code invalid_expression — not a numeric result

CAPTCHA​

"CAPTCHA verification failed" error​

The registration, invitation-registration, resend-verification, and password-reset forms all require a valid CAPTCHA token. This error means the token was rejected by the CAPTCHA service.

  • Reload the page and try again — CAPTCHA tokens are single-use and expire quickly.
  • Check your browser's ad blocker or content security policy — some browser extensions block the CAPTCHA widget from loading. Try in a private/incognito window with extensions disabled.
  • If you are using the REST API directly, ensure the captcha_token field contains the token returned by the CAPTCHA widget and that it has not already been used.

The CAPTCHA widget does not appear​

  • Ensure JavaScript is enabled in your browser.
  • Check the browser console for network errors when loading the CAPTCHA widget script.