
sempera
io.github.Sempera-AI/sempera
Sempera MCP, stdio or hosted. Phone tools need a plan and owner approval per call.
Documentation
Sempera MCP server
Documentation | MCP guide | OpenAPI document | MIT licence
@sempera/mcp 0.1.1 is a Model Context Protocol server for the Sempera API. It runs on your machine over stdio and lets an AI assistant (Claude Desktop, Claude Code, Cursor, VS Code and other MCP clients) read your AI phone agents, calls, conversations and numbers, and, only if you turn it on, place a call or send a text.
It calls the public API at https://api.sempera.org (contract: /openapi.json) with your workspace API key. Sempera also hosts an MCP endpoint at https://api.sempera.org/v1/mcp for clients that connect over HTTP; this package is the local, stdio alternative.
Install in your assistant
Two connections. They do not offer the same tools.
Hosted, for an assistant that speaks streamable HTTP:
https://api.sempera.org/v1/mcp
The endpoint answers one JSON body per POST and does not open an event stream. A host can sign in with OAuth: it registers itself, and PKCE with S256 is required. An OAuth grant can hold only phone:read, phone:call and phone:text. Phone tools need a Sempera Phone plan. Each call needs owner approval unless a standing approval covers that preview. A preview places no call. Read tools and builder tools are not on an OAuth grant. They need a bearer API key whose scopes allow them. The live tool list is what tools/list returns for that credential.
On your machine, over stdio:
npx -y @sempera/mcp
Set SEMPERA_API_KEY, or use a key saved by sempera login. Read tools are always on. send_call and send_sms are off unless you pass --allow-writes. This package does not serve the hosted phone, read or builder tools. Client config for this package is under Configure your MCP client.
Install
Node.js 20 or newer.
# From npm (MCP clients usually run it with npx, below)
npm install -g @sempera/mcp
# From source
git clone https://github.com/Sempera-AI/sempera-mcp.git
cd sempera-mcp
npm install
Create an API key in the Sempera App under Settings, API keys. Give the key only the scopes you want the assistant to have.
Configure your MCP client
Claude Desktop (claude_desktop_config.json), Cursor (.cursor/mcp.json) and most other clients use this shape:
{
"mcpServers": {
"sempera": {
"command": "npx",
"args": ["-y", "@sempera/mcp"],
"env": { "SEMPERA_API_KEY": "<your API key>" }
}
}
}
From a source checkout, use "command": "node" and "args": ["/path/to/sempera-mcp/bin/sempera-mcp.js"].
Claude Code:
claude mcp add sempera --env SEMPERA_API_KEY=<your API key> -- npx -y @sempera/mcp
VS Code (.vscode/mcp.json):
{
"servers": {
"sempera": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@sempera/mcp"],
"env": { "SEMPERA_API_KEY": "<your API key>" }
}
}
}
If you have run sempera login with the Sempera CLI on the same machine, you can leave SEMPERA_API_KEY out: the server reads the same saved key (OS keychain, or the 0600 config file).
Tools
Read tools are always on. None of them changes anything or contacts anyone.
| Tool | What it returns | API |
|---|---|---|
get_credential | The key's workspace, role and scopes | GET /v1/me |
list_agents | Agents, with status and published version | GET /v1/agents |
get_agent | One agent in full | GET /v1/agents/{agent_id} |
list_calls | One agent's phone calls, newest first | GET /v1/calls |
get_call | One call, with its transcript when there is one | GET /v1/calls/{call_id} |
list_conversations | One agent's conversations on every channel | GET /v1/sessions |
get_conversation | One conversation with its transcript | GET /v1/sessions/{session_id} |
list_phone_numbers | Numbers bound to one agent | GET /v1/phone-numbers |
list_sms_numbers | Numbers that can send texts | GET /v1/sms/numbers |
verify_webhook_signature | Whether an X-Sempera-Signature header matches a body and secret (local, no request) | none |
Write tools are off unless you start the server with --allow-writes (or set SEMPERA_MCP_ALLOW_WRITES=1):
| Tool | What it does | API |
|---|---|---|
send_call | Places one real outbound phone call | POST /v1/calls |
send_sms | Sends one real text message | POST /v1/sms/send |
"args": ["-y", "@sempera/mcp", "--allow-writes"]
The write tools have no defaults. Every call must name the agent, the recipient in E.164 form, a consent sentence saying why the person agreed to be contacted, and an idempotency key (send_sms also needs the sending number and the exact message). Their descriptions tell the assistant to show you the details and wait for your confirmation, and they are marked as non-read-only so MCP clients ask before running them. The API still applies calling and sending hours, the do-not-contact list, opt-outs, caps and billing, and sending needs an owner key with the calls:write scope. Reusing the same idempotency key replays the first answer instead of contacting the person twice.
Answers are the API's JSON. Call and conversation reads can include transcripts and phone numbers, as the key's scopes allow. A refusal comes back as a tool error carrying the API's code, message and request_id.
Environment
| Variable | Use |
|---|---|
SEMPERA_API_KEY | The API key; overrides a saved one |
SEMPERA_BASE_URL | Another API base URL |
SEMPERA_MCP_ALLOW_WRITES | 1 to offer send_call and send_sms |
SEMPERA_CONFIG_DIR | Where a key saved by sempera login lives |
SEMPERA_NO_KEYCHAIN | 1 to never use the OS keychain |
Development
npm install
npm test # a real MCP client against the server; the HTTP layer is mocked
npx @modelcontextprotocol/inspector node bin/sempera-mcp.js # try it by hand
src/client.js, src/webhooks.js and src/credentials.js are shared with the Sempera CLI and kept identical to it.
This repository is published from Sempera's main source tree; open issues and pull requests here and they are carried back.
MCP Registry release
server.json lists io.github.Sempera-AI/sempera and pins the npm package version. The matching mcpName in package.json proves the npm package belongs to that listing. npm always includes package.json; the files list selects files, not fields. The packing test checks that the actual tarball keeps this metadata and server.json.
Publish the npm package first. Then, from an account with Actions write access to this repository, run:
gh workflow run publish-mcp-registry.yml --repo Sempera-AI/sempera-mcp --ref main
The workflow is manual only. It installs the official mcp-publisher Linux amd64 release and uses GitHub OIDC to publish the listing. No repository secrets are needed. The workflow does not publish to npm.
License
MIT. Copyright (c) 2026 Sempera Labs, Inc. See the LICENSE file.
@sempera/mcpnpm install @sempera/mcp