> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nixflex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server

> Manage your Nixflex account from Claude Desktop, Cursor, VS Code or any MCP client

`nixflex-mcp` exposes your Nixflex account as tools an AI assistant can use. Once connected, you can say *"call Sam and confirm his Tuesday appointment"* or *"which calls failed today and why?"* and the assistant does it through your account - the same API the dashboard and the CLI use.

It runs on your machine, talks to the assistant over stdio, and calls the official [`nixflex`](https://www.npmjs.com/package/nixflex) SDK. Nothing is hosted by Nixflex; your key never leaves your computer.

## Connect in two steps

<Steps>
  <Step title="Log in once with the CLI">
    ```bash theme={null}
    npx nixflex login
    ```

    The MCP server reads the same stored key, so it needs no configuration of its own.
  </Step>

  <Step title="Add the server to your app">
    ```bash theme={null}
    npx nixflex mcp setup claude     # or: cursor, vscode
    ```

    Then **fully quit** the app (from the system tray, not just the window) and reopen it. The server appears under connectors as **nixflex**.
  </Step>
</Steps>

Prefer to edit the config yourself? This is all `mcp setup` writes:

```json theme={null}
{
  "mcpServers": {
    "nixflex": { "command": "npx", "args": ["-y", "nixflex-mcp"] }
  }
}
```

Claude Desktop: `%APPDATA%\Claude\claude_desktop_config.json` (Windows) or `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS). Cursor: `~/.cursor/mcp.json`. VS Code: `.vscode/mcp.json` under `"servers"`.

If you would rather not store the key, set `NIXFLEX_API_KEY` in the server's `env` block instead - the real value, not `${NIXFLEX_API_KEY}` (desktop apps do not expand variables).

**Other settings.** `NIXFLEX_BASE_URL` in the same `env` block points the server at a staging API. To pin a version instead of taking the latest, use `["-y", "nixflex-mcp@0.2.1"]`. To remove the server, delete the `nixflex` block and restart the app.

Tested with Claude Desktop. Cursor and VS Code use the config formats their own documentation describes; `mcp setup` writes those for you.

## Try it

* "List my Nixflex agents."
* "Show my last 10 calls and tell me which ones ended badly and why."
* "What do we know about +447453573770 on +447450307843? Update the preference to prefers Tuesday mornings."
* "Set the silence hang-up on the Ringback agent to 12 seconds."
* "Import these customers onto +447450307843:" followed by a pasted list.
* "Have the Reception agent call +447700900123 and confirm the appointment on Tuesday at 11."

The last one places a real call and spends credit - the tool description says so, and the assistant will normally ask before running it.

## Tools

Every tool is one API call. Names are `snake_case`; results come back as JSON.

| Area           | Tools                                                                                                                                   |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| Account        | `get_usage`, `rotate_api_key`                                                                                                           |
| Agents         | `list_agents`, `get_agent`, `create_agent`, `update_agent`, `delete_agent`                                                              |
| Calls          | `create_call`, `list_calls`, `get_call`, `delete_call`                                                                                  |
| Campaigns      | `create_campaign`, `launch_campaign`                                                                                                    |
| Phone numbers  | `list_phone_numbers`, `import_phone_number`, `update_phone_number`, `delete_phone_number`, `set_number_monitor`, `set_number_web_calls` |
| Caller context | `get_caller_context`, `set_caller_context`, `import_caller_context`, `delete_caller_context`                                            |
| SMS            | `send_sms`, `create_sms_campaign`, `launch_sms_campaign`, `list_sms_campaigns`, `get_sms_campaign`, `delete_sms_campaign`               |
| Webhooks       | `set_webhook`, `get_webhook`, `delete_webhook`                                                                                          |
| Bring your own | `get_byo_config`, `set_byo_config`, `delete_byo_config`                                                                                 |

`create_agent`, `update_agent`, `update_phone_number`, `import_phone_number`, `create_campaign`, `create_sms_campaign` and `set_byo_config` take a `fields` object passed straight to the API, so every field on the API reference pages is available.

## Safety rails

* **Nothing destructive runs without `confirm: true`.** `delete_*` tools and `rotate_api_key` return a preview of what would happen and change nothing until the assistant calls again with `confirm: true` - which a well-behaved assistant only does after asking you.
* **There is no delete-all tool.** Wiping an account stays a deliberate API or CLI action.
* **Spending tools say so.** `create_call`, `create_campaign`, `send_sms` and `create_sms_campaign` state in their descriptions that they spend credit.
* **Lists are summaries.** `list_calls` returns one line per call (status, duration, summary, sentiment); `get_call` returns the full transcript for one call.
* **Your key stays local.** The server reads `~/.nixflex/config.json` or its own `env`; nothing is sent anywhere except `api.nixflex.com`.
* **The tool list is a contract.** A test in the package starts the real server over stdio and pins all 35 tool names, descriptions and schemas - a tool cannot vanish or change shape without failing the build.

## What it is not

It manages your **account** - agents, numbers, calls, customers. It does not sit inside a live call; the agent on the phone does not use these tools. Letting the phone agent call *external* MCP servers mid-call is a separate feature and is not available yet.

## Troubleshooting

| Symptom                                             | Fix                                                                                                                                                                                                                    |
| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **nixflex** does not appear in the connectors list  | The app reads its config on launch - fully quit it (system tray → Quit) and reopen. Check the JSON is valid.                                                                                                           |
| Server shows but every tool fails with "No API key" | Run `npx nixflex login`, or set the real key in the server's `env` block.                                                                                                                                              |
| "Key rejected"                                      | The key must be the full pair `nxf_xxx:nxfs_xxx`.                                                                                                                                                                      |
| Anything else                                       | Claude Desktop writes the server's log to `%APPDATA%\Claude\logs\mcp-server-nixflex.log` (Windows) or `~/Library/Logs/Claude/mcp-server-nixflex.log` (macOS). The server logs to stderr only - stdout is the protocol. |

## Related

* [CLI](/cli/overview) - the same account from a terminal
* [Node SDK](/sdks/node) - what the tools call underneath
* [API reference](/api-reference/introduction) - every field the `fields` objects accept