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

# Connect Muse to a Sempera number

> Build a Muse custom connector from the OpenAPI document with a scoped phone credential, and the routes it uses.

Muse has no form for adding an MCP server, but it can build a custom connector from an API description. Point it at Sempera's OpenAPI document and give it a scoped REST credential.

Status: **Unverified**. The server side is built and tested against the published standards, but no real Muse account has completed the connection yet ([Supported clients](https://docs.sempera.org/supported-clients.md#ai-assistants)). If a screen differs from these steps, tell [hello@sempera.org](mailto:hello@sempera.org) and this page will be corrected. Meta publishes no developer reference for Muse connectors that Sempera could check, so these steps come from public guides.

## Create a credential

In the Sempera App, open Settings, Connected clients and create a credential for Muse with only the phone permissions you want. The credential is shown once; it appears in Connected clients until you revoke it.

## Build the connector

1. Ask Muse to build a custom connector from `https://api.sempera.org/openapi.json`.
2. When Muse asks for the key, use its secure credential entry, never the chat.
3. Muse sends it as a bearer token on the phone routes.

## The routes Muse uses

| Route | Permission | What it does |
| - | - | - |
| `GET /v1/phone-profile` | `phone:read` | The number, the plan state and what is left |
| `POST /v1/phone-tasks/preview` | `phone:call` | Prepare a call and get an approval link |
| `POST /v1/phone-tasks` | `phone:call` | Start the call you approved |
| `GET /v1/phone-tasks/{task_id}` | `phone:read` | Follow a call to its outcome |
| `POST /v1/phone-tasks/{task_id}/cancel` | `phone:call` | Stop a call: nothing happens before the dial, a live call is hung up |
| `POST /v1/phone-messages/preview`, `POST /v1/phone-messages` | `phone:text` | Prepare and send an approved text |
| `GET /v1/phone-threads/{thread_id}` | `phone:text` | Read a text thread, other people's lines marked `untrusted` |

## 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:

```bash cURL theme={null}
curl https://api.sempera.org/v1/phone-profile \
  -H "Authorization: Bearer $SEMPERA_PHONE_KEY"
```

```python Python theme={null}
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())
```

```js Node theme={null}
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

1. 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.
2. You open the link signed in to Sempera, read the exact request and approve or decline. The approval is good for five minutes.
3. The assistant calls `phone_start_call` with the same values. Any change is refused. The task moves to `reserved`, which means queued, not dialling.
4. 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](https://docs.sempera.org/phone-plan.md).

## 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.

Muse 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 Muse.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.