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.

Prefer zero setup? Use the cloud connection instead, no installation, automatic updates, and OAuth authentication.

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 (generate one in the Developer Portal)

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

Get Your API Key

Log in to your SmartAlex Dashboard
Open the Developer Portal from the side navigation
Generate a new API key
Choose your environment:
- sa_live_, production data
- sa_test_, staging/test data
Copy the key immediately, it won’t be shown again

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 API key from the dashboard

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 provides the same 28 tools, 7 resources, and 5 prompts as the cloud endpoint:

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`

See the Tools Reference for the complete list with parameters and examples.

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 in the dashboard
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)	OAuth (browser) or API key
Transport	stdio	HTTP Streamable
Updates	Manual (`@latest`)	Automatic
Offline	No (needs SmartAlex API)	No
Best for	Claude Desktop, Cursor, VS Code	Claude Code, ChatGPT
Version control	Pin to specific version	Always latest

When to use local: 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: You want zero setup, automatic updates, or OAuth-based authentication. Set up cloud connection →

Next Steps

Usage Examples, Real-world workflows and conversation examples
Tools Reference, Complete reference for all 28 tools
Error Reference, Error codes and troubleshooting

​npm Package Setup

​Install

​Get 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

Get 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