Setup

The three Analytics tools are added in the Node.js 0.7.0 / Python 0.4.0 source release. Remote deployment and npm/PyPI publication are separate steps. Check your endpoint’s tools/list for availability.

Connect directly to Remote MCP (Streamable HTTP) to use all 32 tools. A local stdio proxy is also available, but its tools and parameters depend on the package and version. Check MCP tools/list for the actual catalog.

	Local stdio proxy	Direct remote HTTP
Package/URL	`@duzzle/shanone-mcp` (npm)	`https://mcp.shanone.ai/mcp`
Requires Node.js locally	Yes (18+)	No
Auth needed	API key only	API key and organization ID
Best for	Clients requiring stdio	All 32 current tools

Prerequisites

One of the supported clients: Cursor, Claude Code, or Codex
A Shanone account and an API key from Settings → API Keys (starts with sh_)
Node.js 18+ if using the local proxy

Step 1: Get your API key

Go to app.shanone.ai and sign in.

Open API Keys

Go to Settings → API Keys.

Create a key

Click Create API Key, name it, and choose an expiration (30 days by default). You can also choose 7, 60, or 90 days, Custom (1–366 days), or Never. Create the key and copy the plaintext value — shown only once, in the form sh_xxxxxxxxxxxxxxxx. See Expiration for lifetime and renewal details.

Treat your API key like a password. Never commit it to version control or share it publicly.

Step 2: Configure your client

For an HTTP-capable client, configure the following URL and headers. The Cursor direct HTTP tab shows a complete example; the other tabs include proxy configurations for stdio clients.

URL: https://mcp.shanone.ai/mcp
Authorization: Bearer sh_xxxxxxxxxxxxxxxx
X-Org-Id: org_xxxxxxxxxxxxxxxx

Cursor (local proxy)
Cursor (direct HTTP)
Claude Code (local proxy)
Codex (local proxy)

Edit ~/.cursor/mcp.json (or use Cursor Settings → MCP to add a server):

{
  "mcpServers": {
    "shanone": {
      "command": "npx",
      "args": ["-y", "@duzzle/shanone-mcp"],
      "env": {
        "SHANONE_API_KEY": "sh_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

Restart Cursor to load the MCP server.

{
  "mcpServers": {
    "shanone": {
      "url": "https://mcp.shanone.ai/mcp",
      "headers": {
        "Authorization": "Bearer sh_xxxxxxxxxxxxxxxx",
        "X-Org-Id": "org_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

Find your organization ID on the same Settings → API Keys page as your API key.

claude mcp add shanone \
  --env SHANONE_API_KEY=sh_xxxxxxxxxxxxxxxx \
  -- npx -y @duzzle/shanone-mcp

Or edit .mcp.json in your project:

{
  "mcpServers": {
    "shanone": {
      "command": "npx",
      "args": ["-y", "@duzzle/shanone-mcp"],
      "env": {
        "SHANONE_API_KEY": "sh_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

Edit ~/.codex/config.toml:

[mcp_servers.shanone]
command = "npx"
args = ["-y", "@duzzle/shanone-mcp"]

[mcp_servers.shanone.env]
SHANONE_API_KEY = "sh_xxxxxxxxxxxxxxxx"

Replace every placeholder key/org ID above with your actual values.

Plans and connection checks

Remote Skills require Plus / Pro / Team / Enterprise. Free users still see the tools, but execution returns PLAN_UPGRADE_REQUIRED.
shanone_health_check verifies connectivity to Shanone. Use shanone_check_connection to verify provider authentication such as Gmail.
Gmail execution requires a connection_id from shanone_list_connections. Supply it when you receive CONNECTION_SELECTION_REQUIRED.
shanone_create_execution_context, shanone_get_execution_context, and shanone_switch_connection have been removed. Refresh your client’s tool list.
Updated implementations accept shanone_execute_tool.arguments as an object; use {} for no arguments. Reconnect to refresh tools/list and check version and rollout compatibility.

Python proxy (alternative)

A Python package is also available for Python-centric environments:

pip install shanone-mcp

{
  "mcpServers": {
    "shanone": {
      "command": "shanone-mcp",
      "env": {
        "SHANONE_API_KEY": "sh_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

Verify the connection

Open your client's AI chat

Any MCP-connected chat interface.

Ask for a health check

“Check Shanone connection status.”

Confirm the result

shanone_health_check should report a healthy status with your API key valid and the database reachable.

Configuration reference

Setting	Value
Local proxy package	`@duzzle/shanone-mcp` (npm), requires `SHANONE_API_KEY` env var, Node.js 18+
Direct remote URL	`https://mcp.shanone.ai/mcp` (Streamable HTTP)
Auth header (both)	`Authorization: Bearer <api_key>` (also accepts `X-API-Key`)
Extra header (direct only)	`X-Org-Id: <org_id>` (or `?org_id=` query param fallback)

Troubleshooting

401 api_key_required

No API key was sent. Double-check your config’s env/headers block matches exactly what’s shown above.

401 invalid_api_key

The key is missing, malformed, revoked, or expired. Check its status and expiration in Settings → API Keys. For an expired or revoked key, create a new one and update your client configuration; the old key cannot be reactivated. See Expiration.

401 org_id_required / 403 invalid_org_id (direct HTTP only)

You’re using the direct /mcp endpoint without (or with the wrong) X-Org-Id. Copy the exact organization ID from Settings → API Keys, or switch to the local proxy, which doesn’t need it.

429 rate_limit_exceeded

You’ve exceeded your key’s rate limit. Wait for the duration in the Retry-After header, or ask an admin to raise the limit.

Tools not appearing

Fully restart your client after editing the config.
Check for JSON/TOML syntax errors.
Confirm the server name in the config matches what you reference (usually shanone).
If using the local proxy, run npx -y @duzzle/shanone-mcp directly in a terminal to see startup errors.

Security best practices

Use environment variables

Where your client supports it, reference an environment variable instead of hardcoding the key in a committed config file.

Name keys per machine/agent

So you can revoke one without affecting others.

Rotate periodically

Before a key expires, create a new one from Settings → API Keys, update your client configuration, and confirm it works before revoking the old key.

MCP

Prerequisites

Step 1: Get your API key

Step 2: Configure your client

Plans and connection checks

Python proxy (alternative)

Verify the connection

Configuration reference

Troubleshooting

Security best practices

Next Steps

Shanone MCP Server

Tools Reference

​Prerequisites

​Step 1: Get your API key

​Step 2: Configure your client

​Plans and connection checks

​Python proxy (alternative)

​Verify the connection

​Configuration reference

​Troubleshooting

​Security best practices

​Next Steps

Shanone MCP Server

Tools Reference

Prerequisites

Step 1: Get your API key

Step 2: Configure your client

Plans and connection checks

Python proxy (alternative)

Verify the connection

Configuration reference

Troubleshooting

Security best practices

Next Steps