Skip to main content

npm Package Setup

The @smartalex/mcp-server npm package lets you run AiSky’s MCP server locally on your machine. It communicates with your AI client over stdio and authenticates to AiSky’s API using your API key.
This is the older local package. It needs an API key, which owners and admins can create as a read-only key in Settings → Webhooks & API. Most people should connect to https://mcp.getsmartalex.com by signing in instead. See Getting started.

Install

No global install needed. Your AI client runs the package via npx:
Requirements:
  • Node.js 18 or later
  • A AiSky API key (owners and admins create a read-only key in Settings → Webhooks & API)
Package details:

Your API Key

The package reads its key from the SMARTALEX_API_KEY environment variable. Keys start with:
  • sa_live_, production data
  • sa_test_, staging/test data
Owners and admins create a key in Settings → Webhooks & API, and keys they create are read-only. Most people should connect to the hosted server by signing in instead.
Keep your API key secret. Never commit it to version control or share it publicly. Use environment variables instead.

Client Setup

Claude Desktop

Add AiSky to your Claude Desktop configuration file.
Edit ~/Library/Application Support/Claude/claude_desktop_config.json:
After saving: Fully quit Claude Desktop and reopen it. The AiSky tools will appear in the tool menu (hammer icon).

Claude Code

Set your API key as an environment variable:
Verify the connection:
You should see smartalex listed with 28 tools.

Cursor

Add to .cursor/mcp.json in your project root (project-level) or ~/.cursor/mcp.json (global):
After saving: Restart Cursor or use the command palette: Developer: Reload Window.

VS Code (GitHub Copilot)

Add to .vscode/mcp.json in your project:

Windsurf

Add to your Windsurf MCP configuration:

Gemini CLI

Add to your Gemini CLI settings file at ~/.gemini/settings.json:
After saving, restart Gemini CLI or run /mcp to connect.

Configuration

Environment Variables

The API key is the only configuration needed. The server automatically connects to AiSky’s production API gateway.

Version Pinning

To lock to a specific version (recommended for production automations):

Updating

To update to the latest version:
Or install globally for faster startup:
Then use @smartalex/mcp-server (without npx) as the command in your config:

What’s Included

The npm package has its own 28 tools, 7 resources, and 5 prompts: These are not the same tools as the cloud endpoint, which has 103. The Tools Reference documents the cloud endpoint, so some tools listed there are not in this package.

Architecture

  1. Your AI client spawns the MCP server as a local process
  2. Communication happens over stdio (stdin/stdout)
  3. The server authenticates to AiSky’s API using your API key
  4. All data stays within your AiSky workspace, workspace isolation is enforced server-side

Troubleshooting

”Authentication failed” or 401 errors

  • Verify your key starts with sa_live_ or sa_test_
  • Check the key hasn’t expired or been revoked
  • Confirm the environment variable is set:

Tools not appearing

  • Restart your AI client completely after config changes
  • Claude Desktop: Fully quit (not just close window) and reopen
  • Cursor: Command palette > Developer: Reload Window
  • Claude Code: Run /mcp to check server status

First run is slow

The first npx @smartalex/mcp-server downloads the package (~20 kB + dependencies). Subsequent runs use the npx cache and start in under 2 seconds.

Windows: “npx is not recognized”

Ensure Node.js is installed and in your PATH:
If not installed, download from nodejs.org.

Windows: spawn errors

Windows requires the cmd /c wrapper. See the Windows tab in the setup section above.

npm Package vs Cloud

When to use local: You already have an API key, and your organization requires local tool execution, you want to pin a specific version, or your AI client only supports stdio transport. When to use cloud: In almost every case. No setup, automatic updates, all 103 tools, and you sign in instead of using an API key. Set up the cloud connection →

Next Steps