Troubleshooting

"missing API key" or a 401 from any tool

Every tool call needs a credential — an shb_… key (local server) or either an shb_… key or a sherlock OAuth token (hosted server, see hosted MCP). If a call fails with something like "missing API key" or 401/invalid_api_key, log in again:

npx -y shebang-mcp login

This starts a fresh device-login flow (see device login): it prints a code and a URL, tries to open a browser, and polls until a human approves it. On approval it writes the new key locally and every future tool call in this server (or any other harness pointed at the same machine) picks it up automatically.

401 vs. 403 insufficient_scope

These mean different things — don't treat them the same:

• 401 — the credential itself is missing, unrecognized, expired, or revoked. Nothing about it is trusted at all; log in again.
• 403 insufficient_scope — the credential is valid, but doesn't cover this call: an app key missing the needed apps scope, a key or token trying to reach a project it isn't homed in or granted onto, or a master-only tool (key_*, oauth_*, email_send) called with an app key. Naming a project a key can't reach fails this way too — never a not-found error, so a project's existence is never leaked to a credential that can't reach it. The fix here isn't logging in again; it's a different key, or a grant (project_grant_key) onto the project you're targeting.

project_create / project_set: 400 on color

color is a curated enum, not an arbitrary hex value — passing anything else 400s. The accepted values are exactly: #ef4444, #f97316, #f59e0b, #84cc16, #22c55e, #14b8a6, #06b6d4, #3b82f6, #6366f1, #8b5cf6, #a855f7, #ec4899. Both tools reject a value outside this list client-side, before any network call, and list the full set in the error.

store_upload_content: 415 unsupported file type

store_upload_content (the hosted server's upload tool — see hosted MCP) has no local file to read an extension from, so the platform infers the content type from path's extension alone, never from contentType. If path is missing an extension (or omitted entirely — it falls back to slug, which is rarely a recognizable extension), the upload 415s. Add a real extension to path (e.g. "notes.txt" rather than "notes"), or rely on the tool's own client-side fallback: for a handful of common contentType values (image/png, image/jpeg, image/gif, image/webp, image/svg+xml, text/plain, application/json, application/pdf, video/mp4, audio/mpeg) it appends the matching extension itself before ever calling the platform. Anything outside that list needs an explicit extension in path.

sherserve does not host HTML — there's no contentType value or path extension that gets an HTML upload past this 415. Publish HTML with sherpage_publish instead.

base_run_sql: one statement per call

base_run_sql runs exactly one SQL statement per call — it isn't a multi-statement script runner. Split a migration or setup script into one base_run_sql call per statement.

Next

Tools reference — every tool's real arguments, including which ones need confirm and what it must equal.