Getting Started with SmartAlex MCP

Connect SmartAlex to your AI app in under 2 minutes. Once connected, you can manage voice agents, campaigns, contacts, and deals through natural conversation. Every app connects the same way: add this address, then sign in to SmartAlex in your browser and press Allow.

https://mcp.getsmartalex.com

There is no API key to create and no password saved in a file. Pick your app to jump straight to its setup:

ChatGPT

Add a custom connector.

Claude

Add a custom connector.

Claude Code

A single command.

Cursor

Add to .cursor/mcp.json.

Codex

Two commands.

Gemini CLI

Add to settings.json.

Prerequisites

A SmartAlex account at getsmartalex.com
An AI app that can connect to a remote MCP server by URL and sign in

What the app can do

Once you sign in, the AI app acts as you, in the workspace you last opened in SmartAlex, with your role’s permissions. Tools your plan, add-ons or role don’t allow are hidden. Actions that spend money, contact real people or delete something for good show you a preview and wait for your yes. Security and permissions covers this in full.

Client Configuration

ChatGPT

Go to Settings, then Connectors (custom connectors). On plans that require it, turn on developer mode first. Choose Add or Create a custom connector, paste the address below, and sign in to SmartAlex when prompted.

https://mcp.getsmartalex.com

Claude (web and desktop)

Go to Customize → Connectors.
Click + Add, then Add custom connector.
Name it SmartAlex, paste https://mcp.getsmartalex.com, and follow the steps to add it.
Press Connect and sign in to SmartAlex when prompted.

On Team and Enterprise plans, an owner adds the connector under Organization settings → Connectors. Members then find it under Customize → Connectors and press Connect.

Claude Code

claude mcp add --transport http smartalex https://mcp.getsmartalex.com

Cursor

Add to .cursor/mcp.json in your project root, or ~/.cursor/mcp.json to use it in every project:

{
  "mcpServers": {
    "smartalex": {
      "url": "https://mcp.getsmartalex.com"
    }
  }
}

Then open Settings → Tools & MCP, find smartalex, press Connect, and sign in.

Codex

codex mcp add smartalex --url https://mcp.getsmartalex.com
codex mcp login smartalex

The second command opens your browser so you can sign in.

Gemini CLI

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

{
  "mcpServers": {
    "smartalex": {
      "httpUrl": "https://mcp.getsmartalex.com"
    }
  }
}

Then start Gemini CLI and run /mcp auth smartalex to sign in. Sign-in opens a browser on the same machine, so it does not work in a session with no browser, such as a remote SSH session.

VS Code and other apps

SmartAlex works with any MCP app that can connect to a remote server by URL and sign in. Use https://mcp.getsmartalex.com.

Signing In

When you connect, your AI app opens SmartAlex in your browser. Sign in and press Allow. The app never sees your password.

The app works in the workspace you last opened in SmartAlex. To work in a different workspace, switch to it in SmartAlex first.
API keys are not self-serve. You don’t need one to connect.
To disconnect an app, open the user menu at the top right of SmartAlex and go to Account → Security → Where you’re signed in. Find the app and press Sign out. Signing out of the SmartAlex website does not disconnect your AI apps.

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 (npm package)
Setup	No installation	Requires Node.js 18+
Auth	Sign in to SmartAlex in your browser	API key, not self-serve
Tools	80	28
Transport	HTTP Streamable	stdio
Updates	Automatic	`npx @smartalex/mcp-server@latest`
Best for	Everyone	Existing setups that already have an API key

Recommendation: Use the cloud server. The npm package is older, has fewer tools, and needs an API key.

Troubleshooting

Sign in again from your AI app. In Claude Code, run /mcp, choose smartalex, then Authenticate. In Codex, run codex mcp login smartalex. In Gemini CLI, run /mcp auth smartalex.
Brand-new account? If this happens straight after you sign in, your workspace may not be set up yet. Open SmartAlex in your browser, finish setting up your workspace, then sign in again.

Tools missing after connecting

Restart or reload your AI app after configuration changes
For Cursor: use the command palette > “Reload Window”
For Claude Code: run /mcp to check server status
Some tools are hidden by your plan, add-ons or role. Campaign tools and buying numbers need the Outbound Campaigns add-on. HTTP tools and creating or deleting webhooks need Power Tools. Creating an agent needs a free agent slot. A tool your role cannot use stays unavailable until a workspace owner or admin changes your role.
The app works in the workspace you last opened in SmartAlex. If you expected a different workspace, switch to it in SmartAlex.

”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 requests per minute per workspace). Wait for the Retry-After header duration and retry. Most AI clients handle this automatically.

Next Steps

Security and permissions, What a connected app can do, what asks you first, and how to disconnect it
Usage Examples, Real-world workflows and conversation examples
Tools Reference, Complete reference for all 80 tools
Error Reference, Error codes and troubleshooting
MCP Overview, Architecture, resources, prompts, and workflows
npm Package Setup, The older local package, which needs an API key

Start here

Install & connect

Reference

Guides

MCP Getting Started

Getting Started with SmartAlex MCP

ChatGPT

Claude

Claude Code

Cursor

Codex

Gemini CLI

Prerequisites

What the app can do

Client Configuration

ChatGPT

Claude (web and desktop)

Claude Code

Cursor

Codex

Gemini CLI

VS Code and other apps

Signing In

Your First Tool Call

More Examples

Cloud vs Local

Troubleshooting

Tools missing after connecting

”reconnection failed” (Cloud)

Rate Limiting

Next Steps

​Getting Started with SmartAlex MCP

ChatGPT

Claude

Claude Code

Cursor

Codex

Gemini CLI

​Prerequisites

​What the app can do

​Client Configuration

​ChatGPT

​Claude (web and desktop)

​Claude Code

​Cursor

​Codex

​Gemini CLI

​VS Code and other apps

​Signing In

​Your First Tool Call

​More Examples

​Cloud vs Local

​Troubleshooting

​”Sign-in expired” or “Invalid or expired token”

​Tools missing after connecting

​”reconnection failed” (Cloud)

​Rate Limiting

​Next Steps

Getting Started with SmartAlex MCP

Prerequisites

What the app can do

Client Configuration

ChatGPT

Claude (web and desktop)

Claude Code

Cursor

Codex

Gemini CLI

VS Code and other apps

Signing In

Your First Tool Call

More Examples

Cloud vs Local

Troubleshooting

”Sign-in expired” or “Invalid or expired token”

Tools missing after connecting

”reconnection failed” (Cloud)

Rate Limiting

Next Steps