Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.getsmartalex.com/llms.txt

Use this file to discover all available pages before exploring further.

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

​
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

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

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

​
Environment Variables

VariableRequiredDescription
SMARTALEX_API_KEYYes (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

FeatureCloudLocal
SetupNo installationRequires Node.js 18+
AuthOAuth (browser) or API keyAPI key only
TransportHTTP Streamablestdio
UpdatesAutomaticnpx @smartalex/mcp-server@latest
OfflineNoNo (still needs SmartAlex API)
Best forClaude Code, ChatGPTClaude 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