npm Package Setup

The @smartalex/mcp-server npm package lets you run SmartAlex’s MCP server locally on your machine. It communicates with your AI client over stdio and authenticates to SmartAlex’s API using your API key.

This is the older local package. It needs an API key, and API keys are not self-serve. 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:

npx @smartalex/mcp-server

Requirements:

Node.js 18 or later
A SmartAlex API key (API keys are not self-serve)

Package details:

Field	Value
Package	`@smartalex/mcp-server`
Version	`0.5.0`
Size	~20 kB (plus dependencies)
Transport	stdio
License	MIT
Registry	npmjs.com/package/@smartalex/mcp-server

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

API keys are not self-serve. If you don’t already have one, 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 SmartAlex to your Claude Desktop configuration file.

macOS
Windows
Linux

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "smartalex": {
      "command": "npx",
      "args": ["@smartalex/mcp-server"],
      "env": {
        "SMARTALEX_API_KEY": "sa_live_your_key_here"
      }
    }
  }
}

Edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "smartalex": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@smartalex/mcp-server"],
      "env": {
        "SMARTALEX_API_KEY": "sa_live_your_key_here"
      }
    }
  }
}

Windows requires cmd /c as the command wrapper. The -y flag auto-accepts the npx install prompt.

Edit ~/.config/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "smartalex": {
      "command": "npx",
      "args": ["@smartalex/mcp-server"],
      "env": {
        "SMARTALEX_API_KEY": "sa_live_your_key_here"
      }
    }
  }
}

After saving: Fully quit Claude Desktop and reopen it. The SmartAlex tools will appear in the tool menu (hammer icon).

Claude Code

claude mcp add smartalex -- npx @smartalex/mcp-server

Set your API key as an environment variable:

# macOS/Linux , add to ~/.zshrc or ~/.bashrc
export SMARTALEX_API_KEY=sa_live_your_key_here

# Windows PowerShell
$env:SMARTALEX_API_KEY = "sa_live_your_key_here"

Verify the connection:

claude /mcp

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):

macOS / Linux
Windows

{
  "mcpServers": {
    "smartalex": {
      "command": "npx",
      "args": ["@smartalex/mcp-server"],
      "env": {
        "SMARTALEX_API_KEY": "sa_live_your_key_here"
      }
    }
  }
}

{
  "mcpServers": {
    "smartalex": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@smartalex/mcp-server"],
      "env": {
        "SMARTALEX_API_KEY": "sa_live_your_key_here"
      }
    }
  }
}

After saving: Restart Cursor or use the command palette: Developer: Reload Window.

VS Code (GitHub Copilot)

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

macOS / Linux
Windows

{
  "mcpServers": {
    "smartalex": {
      "command": "npx",
      "args": ["@smartalex/mcp-server"],
      "env": {
        "SMARTALEX_API_KEY": "sa_live_your_key_here"
      }
    }
  }
}

{
  "mcpServers": {
    "smartalex": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@smartalex/mcp-server"],
      "env": {
        "SMARTALEX_API_KEY": "sa_live_your_key_here"
      }
    }
  }
}

Windsurf

Add to your Windsurf MCP configuration:

{
  "mcpServers": {
    "smartalex": {
      "command": "npx",
      "args": ["@smartalex/mcp-server"],
      "env": {
        "SMARTALEX_API_KEY": "sa_live_your_key_here"
      }
    }
  }
}

Gemini CLI

Add to your Gemini CLI settings file at ~/.gemini/settings.json:

{
  "mcpServers": {
    "smartalex": {
      "command": "npx",
      "args": ["@smartalex/mcp-server"],
      "env": {
        "SMARTALEX_API_KEY": "sa_live_your_key_here"
      }
    }
  }
}

After saving, restart Gemini CLI or run /mcp to connect.

Configuration

Environment Variables

Variable	Required	Description
`SMARTALEX_API_KEY`	Yes	Your SmartAlex API key

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

Version Pinning

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

{
  "mcpServers": {
    "smartalex": {
      "command": "npx",
      "args": ["@smartalex/mcp-server@0.5.0"],
      "env": {
        "SMARTALEX_API_KEY": "sa_live_your_key_here"
      }
    }
  }
}

Updating

To update to the latest version:

# Clear the npx cache and pull the latest
npx @smartalex/mcp-server@latest

Or install globally for faster startup:

npm install -g @smartalex/mcp-server@latest

Then use @smartalex/mcp-server (without npx) as the command in your config:

{
  "mcpServers": {
    "smartalex": {
      "command": "@smartalex/mcp-server",
      "env": {
        "SMARTALEX_API_KEY": "sa_live_your_key_here"
      }
    }
  }
}

What’s Included

The npm package has its own 28 tools, 7 resources, and 5 prompts:

Category	Count	Examples
Tools	28	`smartalex_list_contacts`, `smartalex_create_agent`, `smartalex_update_agent`, `smartalex_get_call`
Resources	7	`smartalex://agents`, `smartalex://deals/pipeline`, `smartalex://workflows`
Prompts	5	`campaign-strategy`, `lead-qualification`, `pipeline-review`

These are not the same tools as the cloud endpoint, which has 80. The Tools Reference documents the cloud endpoint, so some tools listed there are not in this package.

Architecture

┌──────────────┐      stdio       ┌──────────────────────┐     HTTPS      ┌─────────────────┐
│  AI Client   │ ◄──────────────► │  @smartalex/mcp-server │ ────────────► │  SmartAlex API  │
│  (Claude,    │                  │  (runs locally)        │  Bearer token  │  Gateway        │
│   Cursor,    │                  │                        │                │                 │
│   VS Code)   │                  └──────────────────────┘                └─────────────────┘
└──────────────┘

Your AI client spawns the MCP server as a local process
Communication happens over stdio (stdin/stdout)
The server authenticates to SmartAlex’s API using your API key
All data stays within your SmartAlex 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:

echo $SMARTALEX_API_KEY

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:

node --version   # Should print v18.x or later
npx --version    # Should print a version number

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

Feature	npm Package (local)	Cloud Endpoint
Installation	Requires Node.js 18+	None
Auth	API key (env var), not self-serve	Sign in to SmartAlex in your browser
Tools	28	80
Transport	stdio	HTTP Streamable
Updates	Manual (`@latest`)	Automatic
Offline	No (needs SmartAlex API)	No
Best for	Existing setups that already have an API key	Everyone: Claude, ChatGPT, Cursor, Codex, and other MCP apps
Version control	Pin to specific version	Always latest

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 80 tools, and you sign in instead of using an API key. Set up the cloud connection →

Next Steps

Usage Examples, Real-world workflows and conversation examples
Tools Reference, Reference for the cloud endpoint’s 80 tools
Error Reference, Error codes and troubleshooting

Start here

Install & connect

Reference

Guides

npm Package Setup

npm Package Setup

Install

Your API Key

Client Setup

Claude Desktop

Claude Code

Cursor

VS Code (GitHub Copilot)

Windsurf

Gemini CLI

Configuration

Environment Variables

Version Pinning

Updating

What’s Included

Architecture

Troubleshooting

”Authentication failed” or 401 errors

Tools not appearing

First run is slow

Windows: “npx is not recognized”

Windows: spawn errors

npm Package vs Cloud

Next Steps

​npm Package Setup

​Install

​Your API Key

​Client Setup

​Claude Desktop

​Claude Code

​Cursor

​VS Code (GitHub Copilot)

​Windsurf

​Gemini CLI

​Configuration

​Environment Variables

​Version Pinning

​Updating

​What’s Included

​Architecture

​Troubleshooting

​”Authentication failed” or 401 errors

​Tools not appearing

​First run is slow

​Windows: “npx is not recognized”

​Windows: spawn errors

​npm Package vs Cloud

​Next Steps

npm Package Setup

Install

Your API Key

Client Setup

Claude Desktop

Claude Code

Cursor

VS Code (GitHub Copilot)

Windsurf

Gemini CLI

Configuration

Environment Variables

Version Pinning

Updating

What’s Included

Architecture

Troubleshooting

”Authentication failed” or 401 errors

Tools not appearing

First run is slow

Windows: “npx is not recognized”

Windows: spawn errors

npm Package vs Cloud

Next Steps