Getting Started with SmartAlex MCP

Connect SmartAlex to your AI assistant in under 2 minutes. Once connected, you can manage voice agents, campaigns, contacts, and deals through natural conversation. Pick your assistant to jump straight to its setup:

https://mintcdn.com/smartalex/sirBslEh6uou56ET/images/clients/openai.svg?fit=max&auto=format&n=sirBslEh6uou56ET&q=85&s=b8b713760189010df248c4799c829b43

ChatGPT

Hosted cloud endpoint. No install.

https://mintcdn.com/smartalex/sirBslEh6uou56ET/images/clients/claude.svg?fit=max&auto=format&n=sirBslEh6uou56ET&q=85&s=a99573f3e7e3b68a1ce410af0db5b0c6

Claude Desktop

Edit one config file.

https://mintcdn.com/smartalex/sirBslEh6uou56ET/images/clients/anthropic.svg?fit=max&auto=format&n=sirBslEh6uou56ET&q=85&s=7ecbd8c37c36f9c89a95108444d90b9d

Claude Code

A single command.

Cursor

Add to .cursor/mcp.json.

https://mintcdn.com/smartalex/sirBslEh6uou56ET/images/clients/googlegemini.svg?fit=max&auto=format&n=sirBslEh6uou56ET&q=85&s=b5fd8bc0763ed6fc0ad30d19ff75e657

Gemini CLI

Add to settings.json.

VS Code

Add to .vscode/mcp.json.

The fastest path is ChatGPT or Claude Code over the cloud: paste one URL, approve in your browser, and you are connected. No Node.js, no API key, no config files. The local config options further down are for Claude Desktop, Cursor, and VS Code.

Prerequisites

A SmartAlex account at getsmartalex.com
An API key (generate one from the Developer Portal in your dashboard)
Node.js 18+ (for local installation only)

Quick Install

Cloud Connection (Recommended)

No installation required. Connect directly to SmartAlex’s hosted MCP endpoint using OAuth:

# Claude Code , connects via HTTP, authenticates via OAuth
claude mcp add --transport http smartalex https://api.getsmartalex.com/functions/v1/mcp-server

Local Installation

Run locally via npx (no global install needed):

npx @smartalex/mcp-server

Requires SMARTALEX_API_KEY environment variable to be set.

Client Configuration

Claude Code

Cloud (recommended):

claude mcp add --transport http smartalex https://api.getsmartalex.com/functions/v1/mcp-server

Claude Code will prompt you to authenticate via OAuth in your browser. Local:

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

Set your API key first:

export SMARTALEX_API_KEY=sa_live_your_key_here

Claude Desktop

Add to your Claude Desktop configuration file: macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

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

Restart Claude Desktop after saving.

Cursor

Add to .cursor/mcp.json in your project root (or global config):

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

Restart Cursor after saving.

VS Code (GitHub Copilot)

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

{
  "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: Location: ~/.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.

ChatGPT

ChatGPT connects to SmartAlex via the cloud MCP endpoint using OAuth. Add the SmartAlex MCP server in ChatGPT’s MCP settings with:

https://api.getsmartalex.com/functions/v1/mcp-server

Windows Note

On Windows, use cmd as the command wrapper:

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

Authentication Setup

Getting Your API Key

Log in to getsmartalex.com
Open the Developer Portal from the side navigation
Generate a new API key
Choose your environment:
- Production keys start with sa_live_
- Test keys start with sa_test_
Copy the key immediately, it won’t be shown again

Environment Variables

Variable	Required	Description
`SMARTALEX_API_KEY`	Yes (local)	Your API key from the dashboard

# 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"

OAuth 2.0 (Cloud)

Cloud connections use OAuth 2.0. When connecting via HTTP transport, your AI client will open a browser window for authentication. No manual token management needed.

Your First Tool Call

Once connected, try asking your AI assistant:

“Show me my SmartAlex contacts”

The assistant will use the smartalex_list_contacts tool and return your contacts:

{
  "data": [
    {
      "id": "a1b2c3d4-...",
      "first_name": "Sarah",
      "last_name": "Johnson",
      "email": "sarah@example.com",
      "phone": "+15551234567",
      "tags": ["enterprise"],
      "status": "active",
      "created_at": "2026-03-01T10:30:00Z"
    }
  ],
  "meta": {
    "total": 21,
    "page": 1,
    "per_page": 25
  }
}

More Examples

Check platform health:

“What’s the status of my SmartAlex platform?”

Analyze recent calls:

“Show me my recent calls”

Create a contact:

“Add a new contact: John Smith, john@acme.com, +1 555 987 6543”

Review your pipeline:

“Show me all deals in the offer stage”

Create a campaign:

“Create an outbound campaign called Q2 Outreach”

Cloud vs Local

Feature	Cloud	Local
Setup	No installation	Requires Node.js 18+
Auth	OAuth (browser) or API key	API key only
Transport	HTTP Streamable	stdio
Updates	Automatic	`npx @smartalex/mcp-server@latest`
Offline	No	No (still needs SmartAlex API)
Best for	Claude Code, ChatGPT	Claude Desktop, Cursor, VS Code

Recommendation: Use cloud for the fastest setup. Use local if your organization requires local-only tool execution or you want to pin a specific version.

Troubleshooting

”Authentication failed” or “Invalid API key”

Verify your key starts with sa_live_ (production) or sa_test_ (test)
Regenerate the key from the Developer Portal if it may be expired
Check the environment variable is set:

echo $SMARTALEX_API_KEY  # Should print your key

Tools not appearing after connecting

Restart your AI client after configuration changes
For Claude Desktop: fully quit and reopen (not just close the window)
For Cursor: use the command palette > “Reload Window”
For Claude Code: run /mcp to check server status

”reconnection failed” (Cloud)

The cloud MCP server runs in stateless mode. If you see a reconnection error, simply reconnect, each request is independent and doesn’t require a persistent session.

Rate Limiting

If you see HTTP 429 responses, you’ve exceeded the rate limit (100 req/min per workspace for authenticated, 30 req/min per IP for public). Wait for the Retry-After header duration and retry. Most AI clients handle this automatically.

First run is slow (Local)

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

Next Steps

npm Package Setup, Detailed local installation guide with version pinning, updating, and per-client setup
Usage Examples, Real-world workflows and conversation examples
Tools Reference, Complete reference for all 28 tools with parameters and examples
Error Reference, Error codes and troubleshooting
MCP Overview, Architecture, resources, prompts, and workflows

​Getting Started with SmartAlex MCP

ChatGPT

Claude Desktop

Claude Code

Cursor

Gemini CLI

VS Code

​Prerequisites

​Quick Install

​Cloud Connection (Recommended)

​Local Installation

​Client Configuration

​Claude Code

​Claude Desktop

​Cursor

​VS Code (GitHub Copilot)

​Gemini CLI

​ChatGPT

​Windows Note

​Authentication Setup

​Getting Your API Key

​Environment Variables

​OAuth 2.0 (Cloud)

​Your First Tool Call

​More Examples

​Cloud vs Local

​Troubleshooting

​”Authentication failed” or “Invalid API key”

​Tools not appearing after connecting

​”reconnection failed” (Cloud)

​Rate Limiting

​First run is slow (Local)

​Next Steps

Getting Started with SmartAlex MCP

Prerequisites

Quick Install

Cloud Connection (Recommended)

Local Installation

Client Configuration

Claude Code

Claude Desktop

Cursor

VS Code (GitHub Copilot)

Gemini CLI

ChatGPT

Windows Note

Authentication Setup

Getting Your API Key

Environment Variables

OAuth 2.0 (Cloud)

Your First Tool Call

More Examples

Cloud vs Local

Troubleshooting

”Authentication failed” or “Invalid API key”

Tools not appearing after connecting

”reconnection failed” (Cloud)

Rate Limiting

First run is slow (Local)

Next Steps