Troubleshooting

Scan stuck on "in_progress"

Fast scans target p95 under 3 minutes (≤ 20 min hard cap). Deep scans target p95 under 20 minutes (≤ 30 min hard cap). If a scan stays in_progress past those windows:

1. Confirm the input resolves to a real package:

   # For npm
   npm info @scope/package
   # For PyPI
   pip index versions my-package

2. If the package exists, re-submit the scan — transient pipeline issues can occasionally stall a stage.
3. If the problem persists, contact support.

INVALID_REQUEST, REPOSITORY_NOT_FOUND, or NOT_AN_MCP_SERVER

{ "success": false, "error": { "code": "INVALID_REQUEST" } }

These three codes all mean MCPSafe couldn't proceed with the input string. INVALID_REQUEST fires when the parser can't recognize the shape; REPOSITORY_NOT_FOUND fires when the resolved target doesn't exist on the upstream registry; NOT_AN_MCP_SERVER fires when the resolved repo doesn't look like an MCP server (no manifest, no MCP SDK imports). Use one of these formats — see Input formats for the full reference:

@scope/package          # npm scoped
package-name            # npm bare
pypi:package-name       # PyPI (explicit prefix)
github.com/owner/repo   # GitHub URL
owner/repo              # GitHub shorthand
docker:image:tag        # Docker image
io.github.owner/repo    # MCP registry ID

If your input contains a colon (e.g. a PyPI version pin like requests==2.31.0), prefix it with pypi::

# Wrong — colon triggers Docker parser
{"input": "requests:2.31.0"}
 
# Right
{"input": "pypi:requests==2.31.0"}

RATE_LIMITED (429)

Anonymous scans are bucketed across minute / day / week windows. The 429 response body includes which window denied (window: minute|day|week|month) and the current vs. limit count for that window. Options:

• Wait — the Retry-After header tells you when to retry (in seconds)
• Sign up — signed-in accounts get higher per-window limits, visible on the dashboard under Usage stats
• Use an API key — pass Authorization: Bearer mcpsafe_... to use your account's per-key quota (Developer plan and above)

Per-tier monthly caps are listed in the API Overview — Rate limits.

SUBSCRIPTION_REQUIRED (402)

Returned when a free-tier account hits a paid-only feature:

• Submitting a private scan (scan_visibility: "private")
• Minting an API key

Public scans (fast and deep) remain free for signed-in accounts. Upgrade your plan from the pricing page.

Scan shows wrong package

If the scan result names a different package than expected, the input was normalized to a cached variant. Submit with an explicit prefix to force the correct parser:

# Explicit PyPI prefix avoids ambiguous parsing
{"input": "pypi:mcp-server-fetch"}

Badge not updating after rescan

Badges (https://api.mcpsafe.io/api/badge/{scan_id}) are cached for 1 hour at the CDN. Wait an hour and hard-refresh. If the old grade still shows after 90 minutes, contact support.

API key not working

• Verify the key is active in your API keys dashboard
• Pass it as Authorization: Bearer mcpsafe_... (or Bearer mcp_... for legacy keys minted before 2026-04-29) — not X-API-Key
• Keys carry scopes; a scan:read-only key cannot submit scans even if the bearer is otherwise authenticated
• If your plan was downgraded, existing keys remain valid but their rate limit decreases to match the new tier