> ## Documentation Index
> Fetch the complete documentation index at: https://docs.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://mcp.famulor.io">
    mcp.famulor.io — no install required
  </Card>

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

## Overview

The Famulor MCP server exposes the full Famulor platform as **66 tools** your AI assistant can call. Ask in plain language — the model chooses the right tools.

**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"*

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

## Hosted endpoints

| Endpoint            | URL                                                             |
| ------------------- | --------------------------------------------------------------- |
| **MCP (canonical)** | `https://mcp.famulor.io/mcp`                                    |
| **Base URL**        | `https://mcp.famulor.io/` (also accepted)                       |
| **Health**          | [https://mcp.famulor.io/health](https://mcp.famulor.io/health)  |
| **OAuth metadata**  | `https://mcp.famulor.io/.well-known/oauth-authorization-server` |

Both `https://mcp.famulor.io/` and `https://mcp.famulor.io/mcp` work as MCP URLs in connector dialogs.

## 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 |
| **Calls**           | Make outbound calls · list / get / delete call records                                                                                                     |
| **Campaigns**       | Create campaigns, retry rules, allowed-hours windows · start, stop, delete                                                                                 |
| **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 · 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 paste your [Famulor API key](https://app.famulor.de/api-keys).
3. The client receives an access token; the server encrypts it with **AES-256-GCM**.

**Your API key never lands in any database** — it lives only inside the token your client stores. Tokens expire after **30 days**; your client re-prompts for sign-in.

<Warning>
  Do not put your API key in `mcp.json`, environment variables in shared configs, or version control. Use OAuth sign-in through your client.
</Warning>

## 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://mcp.famulor.io` works out of the box. To run your own instance:

### 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 so clients like ChatGPT and Claude can manage your voice agents on your behalf — after you authenticate with your API key via OAuth.

## Resources

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

## License

[MIT](https://github.com/bekservice/Famulor-MCP/blob/main/LICENSE) — see the GitHub repository for details.

<Tip>
  Related pages: [MCP Client](/en/mcp/client), [Famulor Skill](/en/mcp/famulor-skill).
</Tip>