Connect Codex to a Sempera number

Codex reads its MCP servers from config.toml. Add Sempera once, sign in through your browser, and Codex can preview calls and texts for you to approve. Status: Unverified. The server side is built and tested against the published standards, but no real Codex account has completed the connection yet (Supported clients). If a screen differs from these steps, tell hello@sempera.org and this page will be corrected. Add the server to ~/.codex/config.toml, then sign in. Codex opens your browser, registers itself and listens on a loopback port for the answer.

[mcp_servers.sempera]
url = "https://api.sempera.org/v1/mcp"

codex mcp login sempera --oauth-client-registration dcr

Or use a credential

If you prefer a credential in an environment variable, create a REST credential with the phone permissions you want under Settings, Connected clients, and point Codex at it. Codex tries the bearer token before OAuth. An ordinary workspace API key is refused on the phone tools.

[mcp_servers.sempera]
url = "https://api.sempera.org/v1/mcp"
bearer_token_env_var = "SEMPERA_PHONE_KEY"

The phone tools Codex sees

Tool	Permission
`phone_get_profile`, `phone_get_task`	`phone:read`
`phone_preview_call`, `phone_start_call`, `phone_cancel_task`	`phone:call`
`phone_preview_text`, `phone_send_text`, `phone_get_thread`	`phone:text`

The @sempera/ai Codex plugin is a business agent-building kit and has no phone tools.

Check the connection

Ask the assistant for your Sempera Phone number and what is left this period. That is a read: it places nothing and needs only phone:read. The same read over plain HTTP, with a phone credential from Settings, Connected clients:

curl https://api.sempera.org/v1/phone-profile \
  -H "Authorization: Bearer $SEMPERA_PHONE_KEY"

import os, urllib.request

req = urllib.request.Request(
    "https://api.sempera.org/v1/phone-profile",
    headers={"Authorization": f"Bearer {os.environ['SEMPERA_PHONE_KEY']}"},
)
print(urllib.request.urlopen(req).read().decode())

const res = await fetch("https://api.sempera.org/v1/phone-profile", {
  headers: { Authorization: `Bearer ${process.env.SEMPERA_PHONE_KEY}` },
});
console.log(await res.json());

An ordinary workspace API key is refused on the phone routes: every phone credential is a connected client (an OAuth grant, an MCP connection or a REST credential), so it can be revoked on its own.

What happens on a call

The assistant calls phone_preview_call (or POST /v1/phone-tasks/preview) with the number, the task, the permitted_actions and an optional max_minutes. Nothing is dialled or reserved. The answer carries an approval link, or standing: true if a standing approval covers that number.
You open the link signed in to Sempera, read the exact request and approve or decline. The approval is good for five minutes.
The assistant calls phone_start_call with the same values. Any change is refused. The task moves to reserved, which means queued, not dialling.
The assistant follows the task with phone_get_task until completed, failed or cancelled. The result is marked untrusted: it was written from what someone else said.

Texts work the same way with phone_preview_text and phone_send_text. The full rules, limits and refusal codes are in Personal phone plan.

Before the first call

The plan is not open for purchase yet. When it opens, a first call also needs a number on the account and a published Sempera agent pinned to the plan; until then a start is refused with PHONE_PLAN_INACTIVE, PHONE_NUMBER_MISSING or PHONE_AGENT_UNPINNED. Calls and texts go out only while it is between 9 a.m. and 9 p.m. in both Toronto and Vancouver (noon to 9 p.m. Eastern); outside that window they are refused with PHONE_OUTSIDE_HOURS.

Disconnect

Open Settings, Connected clients in the Sempera App and revoke the client. That ends its credential at once and leaves every other assistant working. Codex is a trademark of its owner, used here only to say which assistant connects. Sempera is not affiliated with, sponsored by or endorsed by the maker of Codex.

Get started

Build an agent

Phone numbers

Calls

Tools and integrations

Testing

Workspace and security

SDKs and tools

Connect Codex to a Sempera number

Or use a credential

The phone tools Codex sees

Check the connection

What happens on a call

Before the first call

Disconnect

​Add the server and sign in

​Or use a credential

​The phone tools Codex sees

​Check the connection

​What happens on a call

​Before the first call

​Disconnect

Add the server and sign in

Or use a credential

The phone tools Codex sees

Check the connection

What happens on a call

Before the first call

Disconnect