Repository avatar
Other Tools
v0.1.1
active

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

mcptry

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.

ToolWhat it returnsAPI
get_credentialThe key's workspace, role and scopesGET /v1/me
list_agentsAgents, with status and published versionGET /v1/agents
get_agentOne agent in fullGET /v1/agents/{agent_id}
list_callsOne agent's phone calls, newest firstGET /v1/calls
get_callOne call, with its transcript when there is oneGET /v1/calls/{call_id}
list_conversationsOne agent's conversations on every channelGET /v1/sessions
get_conversationOne conversation with its transcriptGET /v1/sessions/{session_id}
list_phone_numbersNumbers bound to one agentGET /v1/phone-numbers
list_sms_numbersNumbers that can send textsGET /v1/sms/numbers
verify_webhook_signatureWhether 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):

ToolWhat it doesAPI
send_callPlaces one real outbound phone callPOST /v1/calls
send_smsSends one real text messagePOST /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

VariableUse
SEMPERA_API_KEYThe API key; overrides a saved one
SEMPERA_BASE_URLAnother API base URL
SEMPERA_MCP_ALLOW_WRITES1 to offer send_call and send_sms
SEMPERA_CONFIG_DIRWhere a key saved by sempera login lives
SEMPERA_NO_KEYCHAIN1 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.

NPM
@sempera/mcp
Install Command
npm install @sempera/mcp
Runtime: npx

Remote