Skip to main content

​
Connection issues

No API key was sent with the request. Check that your MCP client config includes Authorization: Bearer sh_xxx (or X-API-Key: sh_xxx) exactly as shown in MCP Setup. If you’re using the local stdio proxy, confirm SHANONE_API_KEY is actually set in the env block — a missing env var is the most common cause.
The key is malformed, was revoked, or expired. Create a new key from Settings → API Keys and update your client config. Remember the plaintext key is only ever shown once at creation time — if you lost it, revoke it and create a new one.
You’re connecting straight to https://app.shanone.ai/mcp without the local proxy. This endpoint requires both your API key and your X-Org-Id header — an API key alone isn’t enough. Copy your organization ID from Settings → API Keys and add it as X-Org-Id (or append ?org_id=... to the URL if your client can’t send custom headers). The local stdio proxy (@duzzle/shanone-mcp) doesn’t need this — it only requires the API key.
You’ve exceeded your API key’s rate limit (60 requests/minute and 10,000/day by default). The response includes a Retry-After header — wait that long before retrying. If this happens often, ask a Root/admin to raise the key’s rate_limit in Settings → API Keys.
  1. Fully restart your MCP client after editing its config (a reload isn’t always enough).
  2. Check the config file for JSON syntax errors — a trailing comma will silently break the whole mcpServers block in most clients.
  3. Confirm the server name in your tool calls matches your config’s key (usually shanone).
  4. If using the local proxy, run npx -y @duzzle/shanone-mcp directly in a terminal to see startup errors.

​
Authentication & OAuth

Each service’s OAuth connection is tied to your Shanone user, not your session. Make sure you completed the OAuth flow while signed in as the same Shanone account whose API key your agent is using — connecting Slack while logged in as a teammate won’t help your key.
The stored OAuth token for that service expired or was revoked upstream (e.g. you removed the app’s access from within Slack/Google/etc.). Follow the new connect_link in the response to reauthorize — Shanone stores the refreshed token automatically afterward.

​
Permission errors

The Permission Vendor tools (shanone_set_user_tool_permission, shanone_set_user_service_permission, shanone_get_permission_summary, shanone_batch_set_user_permissions, shanone_list_user_tool_permissions) require the caller to be a Root user, or an SA2 user explicitly delegated the tool-permissions:ManageOthers policy action. Delegated SA2 users additionally cannot modify a Root user’s permissions. Ask your organization’s Root admin to grant that policy action if you need to manage teammates’ access.
A tool-level permission override always takes priority over a service-level override, which in turn takes priority over the role default. Ask a Root/SA2 admin to run shanone_get_permission_summary for your user_id to see exactly what’s enabled, or shanone_list_user_tool_permissions for the raw list of overrides.
This shows up when setting a permission for a tool or service name that doesn’t (yet) exist in Shanone’s catalog — usually a typo. Double-check the exact name with shanone_list_services or shanone_search_tools; the override is still saved and will simply apply automatically once/if that name is registered.

​
Unexpected tool results

Make the shanone_search_tools query more task-specific (see Best Practices) rather than a bare service name — this is especially common on large integrations like Slack, Stripe, and HubSpot where dozens of tools share overlapping keywords.
Some destructive or high-risk tools require an explicit confirmation step. Re-run shanone_execute_tool with the same arguments plus "confirm": true in the JSON payload once you’re sure you want to proceed.
Updated shanone_execute_tool.arguments takes a JSON object, such as {"channel": "#general", "text": "hi"}. Use {} for no arguments. Arrays, null, and scalars are rejected. Legacy JSON strings must decode to an object. If you still receive an error requiring a string, check your endpoint and package version, then reconnect to refresh tools/list.

​
Getting more help

MCP Tools Reference

Full parameter and error-response reference for every tool

Support

Contact the Shanone team

​
Reporting a bug

When reporting an issue, include:
  • The exact tool name and arguments you called (redact secrets)
  • The full response text, including any reason field
  • Which client you’re using (Cursor, Claude Code, direct HTTP, etc.) and whether you’re on the local proxy or the direct /mcp endpoint
  • Whether the same call works from the Shanone web dashboard’s tool tester, if you tried that