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

# MCP Getting Started

> Connect SmartAlex to Claude, Cursor, VS Code, or any MCP-compatible AI assistant in under 2 minutes. Manage voice agents and campaigns through natural conversation.

# 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:**

<CardGroup cols={3}>
  <Card title="ChatGPT" icon="https://mintcdn.com/smartalex/sirBslEh6uou56ET/images/clients/openai.svg?fit=max&auto=format&n=sirBslEh6uou56ET&q=85&s=b8b713760189010df248c4799c829b43" href="#chatgpt" width="24" height="24" data-path="images/clients/openai.svg">
    Hosted cloud endpoint. No install.
  </Card>

  <Card title="Claude Desktop" icon="https://mintcdn.com/smartalex/sirBslEh6uou56ET/images/clients/claude.svg?fit=max&auto=format&n=sirBslEh6uou56ET&q=85&s=a99573f3e7e3b68a1ce410af0db5b0c6" href="#claude-desktop" width="24" height="24" data-path="images/clients/claude.svg">
    Edit one config file.
  </Card>

  <Card title="Claude Code" icon="https://mintcdn.com/smartalex/sirBslEh6uou56ET/images/clients/anthropic.svg?fit=max&auto=format&n=sirBslEh6uou56ET&q=85&s=7ecbd8c37c36f9c89a95108444d90b9d" href="#claude-code" width="24" height="24" data-path="images/clients/anthropic.svg">
    A single command.
  </Card>

  <Card title="Cursor" icon="https://mintcdn.com/smartalex/sirBslEh6uou56ET/images/clients/cursor.svg?fit=max&auto=format&n=sirBslEh6uou56ET&q=85&s=983cf68e9423b5028bee275a30785f18" href="#cursor" width="24" height="24" data-path="images/clients/cursor.svg">
    Add to `.cursor/mcp.json`.
  </Card>

  <Card title="Gemini CLI" icon="https://mintcdn.com/smartalex/sirBslEh6uou56ET/images/clients/googlegemini.svg?fit=max&auto=format&n=sirBslEh6uou56ET&q=85&s=b5fd8bc0763ed6fc0ad30d19ff75e657" href="#gemini-cli" width="24" height="24" data-path="images/clients/googlegemini.svg">
    Add to `settings.json`.
  </Card>

  <Card title="VS Code" href="#vs-code-github-copilot">
    Add to `.vscode/mcp.json`.
  </Card>
</CardGroup>

<Tip>
  **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.
</Tip>

## Prerequisites

* A SmartAlex account at [getsmartalex.com](https://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:

```bash theme={null}
# 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):

```bash theme={null}
npx @smartalex/mcp-server
```

Requires `SMARTALEX_API_KEY` environment variable to be set.

***

## Client Configuration

### Claude Code

**Cloud (recommended):**

```bash theme={null}
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:**

```bash theme={null}
claude mcp add smartalex -- npx @smartalex/mcp-server
```

Set your API key first:

```bash theme={null}
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`

```json theme={null}
{
  "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):

```json theme={null}
{
  "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:

```json theme={null}
{
  "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`

```json theme={null}
{
  "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:

```json theme={null}
{
  "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](https://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

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

```bash theme={null}
# 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:

```json theme={null}
{
  "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](mailto: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:

```bash theme={null}
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](/mcp/npm-package), Detailed local installation guide with version pinning, updating, and per-client setup
* [Usage Examples](/mcp/examples), Real-world workflows and conversation examples
* [Tools Reference](/mcp/tools-reference), Complete reference for all 28 tools with parameters and examples
* [Error Reference](/mcp/errors), Error codes and troubleshooting
* [MCP Overview](/mcp/overview), Architecture, resources, prompts, and workflows