# Smallest MCP Server

MCP server for the [Smallest AI](https://smallest.ai) platform. Manage agents, debug calls, view analytics — directly from your IDE.

## Quick start

### Option A: npm (recommended)

Requires Node.js 20+. Add this to your MCP config (`~/.cursor/mcp.json` for Cursor, `claude_desktop_config.json` for Claude Desktop):

```json
{
  "mcpServers": {
    "smallest": {
      "command": "npx",
      "args": ["-y", "@developer-smallestai/smallest-mcp-server"],
      "env": {
        "ATOMS_API_KEY": "sk_your_key_here"
      }
    }
  }
}
```

Auto-updates to the latest version every time your editor restarts.

### Option B: One-line installer (no dependencies)

**Mac / Linux:**
```bash
curl -fsSL https://raw.githubusercontent.com/smallest-inc/mcp-server/main/install.sh | bash
```

**Windows (PowerShell):**
```powershell
irm https://raw.githubusercontent.com/smallest-inc/mcp-server/main/install.ps1 | iex
```

Downloads a standalone binary, prompts for your API key, and configures Cursor + Claude Desktop automatically. Re-run to update.

### Option C: One prompt

Open a chat in Cursor or Claude Desktop and type:

```
Set up the Smallest MCP server for me.
The npm package is @developer-smallestai/smallest-mcp-server.
My API key is: sk_paste_your_key_here
```

### Verify

Reload your editor, then type: **"List all my agents"**

---

## Available tools

### Read

| Tool | Description |
|---|---|
| `list_calls` | Search and list calls with filters for status, type, date range, agent, phone number |
| `debug_call` | Get detailed info about a single call — status, transcript, errors, analytics, perceived latency, LLM usage with prompt-cache hit %, per-turn LLM timings, tool-call timings |
| `get_latency_summary` | Org-level perceived-latency KPIs (avg/p50/p95/p99), daily trend, and per-pipeline-stage averages over a date range |
| `get_agents` | List agents with their configuration, voice, LLM model, and call stats |
| `get_agent` | Get full details for a single agent |
| `get_agent_prompt` | Read an agent's current system prompt and tools |
| `get_usage_stats` | Usage statistics — total calls, duration, costs, status breakdown |
| `get_campaigns` | List outbound calling campaigns with status and progress |
| `get_phone_numbers` | List phone numbers owned by your organization |
| `get_voices` | List available voices with gender, language, and model filters |
| `get_playbooks` | Read a multi-agent (Playbooks) agent's SOPs, intent router, and shared auth tools |
| `get_branch_draft` | View a branch's pending (unpublished) draft changes |
| `get_revision` | Get a single committed revision's metadata and resolved config |

### Write

Edits are saved to a branch's **draft** (agents use the branch/revision model). Pass an optional `branch_id` to any editing tool — omit it to edit the live branch; if the agent has several branches you'll be asked which one. Run `publish_draft` once to commit.

| Tool | Description |
|---|---|
| `create_agent` | Create a new AI voice agent (`single_prompt`, or `multi_agents` for Playbooks) |
| `update_agent` | Update agent settings — name, prompt, first message, voice, model, language, variables, pre-call API, etc. |
| `add_agent_tool` | Add or update an API-call tool the agent can invoke during a call |
| `remove_agent_tool` | Remove a tool from an agent by name |
| `configure_call_actions` | Enable/disable end_call and set a transfer number — agent-level |
| `add_playbooks` | Add SOP playbooks (intent + prompt + scoped API tools + auth level) to a multi-agent |
| `update_playbook` | Edit, archive, or restore one playbook |
| `configure_playbooks` | Set the intent router, conversation guide, and shared weak/strong auth tools |
| `delete_agent` | Archive (soft-delete) or unarchive an agent |
| `duplicate_agent` | Copy an agent |

### Versioning (branches & revisions)

| Tool | Description |
|---|---|
| `list_branches` | List the agent's branches (which is live, which have a pending draft) |
| `create_branch` | Create a working branch from another branch's head |
| `rename_branch` | Rename a branch |
| `make_branch_live` | Make a branch's head the live (serving) config |
| `publish_draft` | Publish (commit) or discard a branch's pending draft |
| `list_revisions` | List a branch's committed revisions |
| `diff` | Compare two configs (revisions or a branch draft) |
| `test_agent` | Start a test call against a branch's head, its draft, or a specific revision |

### Act

| Tool | Description |
|---|---|
| `make_call` | Initiate an outbound phone call using a specific agent |

### Resources

| Resource | URI | Description |
|---|---|---|
| Platform Overview | `atoms://docs/platform-overview` | Key concepts, call types, statuses, and cost breakdown |

---

## Environment variables

| Variable | Required | Description |
|---|---|---|
| `ATOMS_API_KEY` | Yes | Your Smallest AI API key |
| `ATOMS_API_URL` | No | Atoms API base. Defaults to `https://api.smallest.ai/atoms/v1`. The realtime chat WebSocket base is derived from it. |
| `WAVES_API_URL` | No | Waves API base. Defaults to `https://api.smallest.ai/waves/v1`. |
| `PAYMENTS_API_URL` | No | Payments API base. Defaults to `https://api.smallest.ai/payment/v1`. |

Only `ATOMS_API_KEY` is needed for normal use. The three base URLs exist so the
server can be pointed at a non-production environment.

The hosted HTTP server (`dist/http.js`) takes each caller's key from the
`Authorization` header instead of `ATOMS_API_KEY`, and needs these to verify it:

| Variable | Required | Description |
|---|---|---|
| `CONSOLE_BACKEND_URL` | Yes | console-backend base **including its API prefix**, e.g. `http://console-backend/console/v1`. Keys are checked at `<base>/user/token`, so a base without `/console/v1` (or `/api/v1`) answers 404 and every request fails. |
| `CONSOLE_API_KEY` | Yes | The service key console-backend accepts in `X-API-Key`. |

## Development

```bash
npm ci         # install exactly what package-lock.json pins
npm run dev    # run with tsx
npm run build  # bundle to dist/
```

## Releases

Merging to `main` automatically publishes a new version to npm and GitHub Releases.

**Version bumps are automatic** based on commit messages:

| Commit message contains | Bump | Example |
|---|---|---|
| `new tool`, `new resource`, `add tool`, `add resource` | **minor** (0.2.0 → 0.3.0) | `feat: add new tool for knowledge bases` |
| `BREAKING CHANGE` or `feat!:` | **major** (0.2.0 → 1.0.0) | `feat!: redesign agent config schema` |
| Anything else | **patch** (0.2.0 → 0.2.1) | `fix: handle empty call logs` |

## License

MIT