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

# MCP Server

> Famulor Model Context Protocol server — control voice agents, calls, campaigns, and more from any MCP client

# Famulor MCP Server

Control your Famulor AI voice agents — calls, leads, campaigns, knowledge bases, conversations, WhatsApp, SIP trunks — directly from **ChatGPT**, **Claude**, **Cursor**, **Windsurf**, **VS Code**, and any other MCP-compatible client.

<img src="https://mintcdn.com/famulor/okk2swZ06pjxl-p5/images/provisioning/sip-ai/famulor-mcp-server.png?fit=max&auto=format&n=okk2swZ06pjxl-p5&q=85&s=5a17b0beaacc6a5022fcabee921b3703" alt="Famulor MCP Server" width="1024" height="535" data-path="images/provisioning/sip-ai/famulor-mcp-server.png" />

<CardGroup cols={3}>
  <Card title="Connect a client" icon="desktop" href="/en/mcp/client">
    Setup for ChatGPT, Claude, Cursor, and more
  </Card>

  <Card title="Hosted server" icon="globe" href="https://app.famulor.io/mcp">
    app.famulor.io/mcp — no install required
  </Card>

  <Card title="GitHub" icon="github" href="https://github.com/bekservice/Famulor-MCP">
    Source code and deployment
  </Card>
</CardGroup>

## Overview

The full Famulor MCP endpoint exposes a broad platform tool catalog for developer clients. Ask in plain language — the model chooses the right tools. All tools return structured output and carry title annotations for directory-compatible clients.

**Example prompts:**

* *"Create a German sales assistant using GPT-4.1-mini and the Susi voice"*
* *"Start campaign #42 and add these 50 leads"*
* *"Show me all calls today where the goal wasn't reached"*
* *"Create a 'Clients' folder and move all inbound assistants into it"*

Need inspiration? See [Use Cases & Prompts](/en/mcp/use-cases) — grouped scenarios with ready-to-use prompts and best practices.

<Note>
  New to MCP? Start with [MCP Client setup](/en/mcp/client) — add the server URL, then sign in to Famulor through OAuth in the browser.
</Note>

## Hosted endpoints

| Endpoint                            | URL                                                             |
| ----------------------------------- | --------------------------------------------------------------- |
| **MCP (canonical)**                 | `https://app.famulor.io/mcp`                                    |
| **Assistant & History (read-only)** | `https://app.famulor.io/mcp?profile=assistant-history`          |
| **Base URL**                        | `https://app.famulor.io/mcp`                                    |
| **Health**                          | [https://app.famulor.io/health](https://app.famulor.io/health)  |
| **OAuth metadata**                  | `https://app.famulor.io/.well-known/oauth-authorization-server` |

Use the restricted Assistant & History URL for ChatGPT and Claude directory or consumer-facing connectors. Use the canonical endpoint for developer clients that intentionally need the full catalog.

## What you can do

| Area                 | Capabilities                                                                                                                                                                                        |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Assistants**       | Create, update, delete AI voice agents · list voices, languages, LLM/multimodal models, TTS/STT providers · toggle inbound and conversation-ended webhooks · organize via `folder_id` / `label_ids` |
| **Folders & Labels** | Organize assistants into folders (one folder per assistant) · tag with colored labels (multiple per assistant) · create, rename, delete                                                             |
| **Calls**            | Make outbound calls · list / get / delete call records                                                                                                                                              |
| **Campaigns**        | Call, WhatsApp & SMS campaigns · schedule windows · get/list/create · start, stop, delete · call→text fallback                                                                                      |
| **Leads**            | Add leads (incl. secondary contacts) · update status and merge variables · delete                                                                                                                   |
| **Knowledge bases**  | Create knowledge bases · upload website-scraped documents · update / delete                                                                                                                         |
| **Phone numbers**    | Search by country and dial pattern · purchase · set nickname (`update_phone_number`) · release · SIP trunk CRUD                                                                                     |
| **Conversations**    | List, read, reply to chats · enable/disable AI per conversation (human takeover)                                                                                                                    |
| **WhatsApp**         | List senders and templates · check 24h session window · send template or freeform messages                                                                                                          |
| **SMS**              | Send via your purchased numbers                                                                                                                                                                     |
| **Mid-call tools**   | Register custom HTTP integrations the assistant can call mid-conversation                                                                                                                           |
| **AI Replies**       | Generate context-aware replies for external chat platforms                                                                                                                                          |

## Authentication

The server uses **MCP OAuth 2.1** (RFC 8414 metadata, RFC 7591 Dynamic Client Registration, PKCE S256):

1. Your MCP client opens a browser tab.
2. You sign in to your normal Famulor account and review the requested permissions.
3. After approval, the client receives a scoped access token.

The hosted OAuth flow does not ask you to paste an API key. The Assistant & History profile requests only `assistants:read` and `calls:read`.

## Supported clients

* **ChatGPT** — custom app with OAuth ([setup guide](/en/mcp/client#chatgpt))
* **Claude** — Desktop connector and Claude Code CLI ([setup guide](/en/mcp/client#claude))
* **Cursor**, **Windsurf**, **VS Code**, **Cline**, **Continue**, **Zed**

See [MCP Client](/en/mcp/client) for step-by-step instructions per client.

## Demo video

<iframe className="w-full aspect-video rounded-xl" src="https://www.youtube.com/embed/OMQeTiBNW3Q" title="Famulor MCP Server Demo" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />

## Self-hosting

The hosted server at `https://app.famulor.io/mcp` works out of the box. To run your own instance:

### Run locally via npm (stdio)

The server is published to npm as [`famulor-mcp`](https://www.npmjs.com/package/famulor-mcp). Run it as a local **stdio** MCP server — no hosting, no OAuth:

```bash theme={null}
npx -y famulor-mcp          # or: npm i -g famulor-mcp && famulor-mcp
```

Point a client at it with a stdio config, passing your [API key](https://app.famulor.io/api-keys) as an env var:

```json theme={null}
{
  "mcpServers": {
    "famulor": {
      "command": "npx",
      "args": ["-y", "famulor-mcp"],
      "env": { "FAMULOR_API_KEY": "your-api-key" }
    }
  }
}
```

<Note>For most setups the hosted server (`https://app.famulor.io/mcp` with OAuth sign-in) is simpler — use the npm package when you need a local, offline, or embedded stdio server.</Note>

### Deploy to Vercel

```bash theme={null}
git clone https://github.com/bekservice/Famulor-MCP.git
cd Famulor-MCP
vercel --prod
```

Set these environment variables in the Vercel project:

| Variable     | Required    | Value                                           |
| ------------ | ----------- | ----------------------------------------------- |
| `MCP_SECRET` | yes         | `openssl rand -hex 32` — encrypts OAuth tokens  |
| `MCP_ISSUER` | recommended | Your public URL, e.g. `https://mcp.example.com` |

Point your domain at the deployment. See the [DEPLOYMENT.md](https://github.com/bekservice/Famulor-MCP/blob/main/DEPLOYMENT.md) guide in the repository for stdio mode and full details.

### Local development

```bash theme={null}
npm install
echo "MCP_SECRET=$(openssl rand -hex 32)" > .env
npm run dev:http
# server on http://localhost:8787
```

```bash theme={null}
curl http://localhost:8787/health
curl http://localhost:8787/.well-known/oauth-authorization-server
```

## About MCP

[Model Context Protocol (MCP)](https://modelcontextprotocol.io/) lets AI assistants securely connect to external tools and data. The Famulor MCP server maps platform APIs to MCP tools after you authenticate with your Famulor account through OAuth.

## Resources

* [Use Cases & Prompts](/en/mcp/use-cases)
* [MCP Client setup](/en/mcp/client)
* [Famulor API reference](/en/api-reference/)
* [Get an API key](https://app.famulor.io/api-keys)
* [GitHub — Famulor-MCP](https://github.com/bekservice/Famulor-MCP)
* [Famulor platform](https://app.famulor.io)

## License

See the current [repository license](https://github.com/bekservice/Famulor-MCP/blob/main/LICENSE) for the self-hosted package terms.

<Tip>
  Related pages: [Use Cases & Prompts](/en/mcp/use-cases), [MCP Client](/en/mcp/client), [Famulor Skill](/en/mcp/famulor-skill).
</Tip>