MCP: connect a coding agent or an assistant

​

Connect

curl -X POST https://api.sempera.org/v1/mcp \
  -H "Authorization: Bearer sempera_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"mcp_client_setup","arguments":{"client":"claude-code"}}}'

​

Sign in with OAuth

1. The host posts without a token and gets 401 with WWW-Authenticate: Bearer resource_metadata="https://api.sempera.org/.well-known/oauth-protected-resource/v1/mcp".
2. It reads that document, then https://api.sempera.org/.well-known/oauth-authorization-server.
3. It registers itself at POST /v1/oauth/register (RFC 7591) and sends the browser to GET /v1/oauth/authorize with PKCE (S256, required), the resource https://api.sempera.org/v1/mcp, and the scopes it wants. Redirects match exactly. A loopback address may differ by port alone, because a native client binds a free port each time.
4. The person signs in on app.sempera.org if they have not, and a workspace owner approves on the consent page: which client, which workspace, which scopes, and where the answer goes. A client Sempera cannot recognise by its published redirect is shown as unverified. The owner can approve fewer scopes than were asked for, never more.
5. The host swaps the code at POST /v1/oauth/token. An access token lasts one hour and a refresh token 30 days. Each refresh turns the refresh token over. Presenting a spent one ends every token from that sign-in, and so does presenting a spent code.

​

Protocol versions

​

Which clients move

• A client that sends the header. The revisions from 2025-06-18 on require a client to send MCP-Protocol-Version on every request after initialize, so a client built on a current SDK sends it. Such a client now negotiates 2025-06-18 (it asks for a newer revision and is answered with the newest spoken), then gets 202 for its notifications/initialized, and may try to open a stream with a GET on the endpoint and be answered 405, which that revision allows for a server that offers none. This is a change from the endpoint before this release, which answered such a client 2024-11-05 and 200. A client that sends a header naming any other revision is refused with 400.
• A client that sends no header on any request. Three of the answers it already got change: initialize asking for 2025-06-18 or newer is answered 2025-06-18 (it was 2024-11-05); tools/list with a cursor is a -32602 error (it was ignored, and the list never paged); and each of the three original tools gains title, annotations and _meta in tools/list. Its tools/list also now carries the 26 added tools. Every other answer to it is unchanged, including the original tools’ results and their -32000 errors.
• A browser page on another site. See the Origin rule below. The API answers a browser’s preflight for this endpoint with 401 and no CORS headers, so such a page could not send it a JSON request with a key in the first place; the Origin rule is a second lock.

​

Origin

​

Tools

​

Arguments, answers and errors

• An agent is named agent_id in every tool, whichever path variable the route calls it. Ids are letters, digits, ., _, : and -, up to 200 characters. An unknown argument, a missing required one, a wrong type or an out-of-range number is refused before anything is read, with the argument named.
• An answer is the route’s JSON as text in one text content item (narrowed as a later section says for nine tools), or, for the two guide tools, its Markdown. A failure is a tool result with isError: true whose text is the route’s own error envelope, for example {"error":{"code":"not_found","message":"no such agent","request_id":"req_..."}}. The codes are those in Errors and limits, and request_id is the one the call returned in X-Request-Id. An answer about your workspace never carries an internal address, the name of a setting, a file path, a stack trace or the name of an engine or supplier behind Sempera; the tests scan every tool’s answer for them.
• Arguments that are not a JSON object, an unknown method and an unknown cursor on tools/list are protocol errors (-32602, -32601). The three original tools keep reporting a refusal as JSON-RPC error -32000, as they always did; every newer tool reports it as a tool result.
• Lists page with limit (1 to 200, default 50; list_agent_check_runs takes 1 to 100) and cursor. Pass next_cursor from the last page back unchanged to read the next one (nextCursor on list_tools, data.next_cursor on list_eval_agents). A cursor is an opaque position: the same cursor gives the same page while the rows are unchanged, and one issued to another key reads only that key’s own rows. list_integrations, list_voices and the environment, branch and deployment reads answer in one piece.
• An answer larger than 1 MiB is refused with payload_too_large; ask for a smaller page or a more specific id. A read that runs longer than 30 seconds is refused with service_unavailable. A call counts once against the key’s request budget (Errors and limits), like any other request.
• A secret environment variable always reads null in list_agent_variables; its value never leaves the server.

​

What nine tools leave out

• Calls and conversation records (list_calls, get_call_log, list_sessions, get_session) return metadata only: the id, the agent, the channel, the status, the start and end times, the duration, the language, the outcome as a code and a label, the version and the number of turns. There is no caller number (not even a masked one), no recording, no transcript, no summary and no title (a phone call’s title is its summary), no extracted values and no provider log. The outcome, the language and the version come from the voice platform’s record of the call, so each is shown only when it has the shape of a short code (letters, digits and . _ : -, no spaces); anything else reads null, and an outcome’s label is shown only when it is one of Sempera’s own outcome labels or the plain wording of its code. No argument switches any of these on. Reading what was said needs a transcript permission that does not exist yet.
• **get_eval_results** returns counts, pass rates, the weekly and per-version trend, and one row per scored conversation with its verdict and score. It leaves out the judge’s reasoning (which quotes the conversation), the failure clusters built from it, the judge’s rubric and the evaluator’s own configuration.
• **list_voices** takes no arguments. It lists the built-in voices an agent may name, with each one’s language and whether it may carry a live call, followed by your workspace’s own ready custom voices. It asks no outside voice library and takes no search, language or provider filter. No other workspace’s voice is ever listed.
• **list_tests and get_test_run** read legacy battery jobs in memory (at most 20 newest), plus candidate checks retained in the App’s canonical Checks ledger on Sempera’s servers. A retained candidate is resolved by id only among the caller’s authorized agents after restart. Legacy jobs are lost at restart. A run shows its state and outcome, not the failure text of a run that crashed nor who started it. Another workspace’s run is answered not found with the same sentence as an unknown id.
• **list_agent_check_runs** returns each check run’s id, agent, version, status and times. A run that ended in an error keeps the status ERROR, and its error_message is always the one sentence “The run ended in an error. Its detail is not returned over MCP.” in place of the system’s own words for what went wrong, which can name a file on a server, a setting or an address.

​

Phone tools

​

Not available over MCP

• Rolling back, archiving or deleting an agent, discarding a draft, buying or releasing a number, running a paid evaluation, changing a variable or a tool. Calls are available only through the separately scoped and approved phone tools described above. The write registry is an explicit list, not arbitrary HTTP access.
• The text of a call, the caller’s number and a call’s summary, until a separate permission for them exists.
• Integration detail by key. list_integrations answers; there is no tool for one integration.
• Post-call event subscriptions, resources and prompts. None of these exist yet, and no page here documents them as live.

​

Draft and test over MCP

• idempotency_key is the request’s identity: a retry with the same value gets the first answer back and changes nothing again; the same value with a different change is refused idempotency_key_reused.
• update_agent_draft needs expect_revision, the revision that get_agent_draft returned. An edit made from an older read is refused conflict with reason: stale_draft, so a newer change by someone else is never overwritten.
• run_agent_tests with candidate_revision and runtime_policy runs the reviewed draft through the App’s canonical Checks runner, never a real call, booking, SMS or email. Without both it retains the legacy battery behavior, but a paid or unknown configured runtime is refused. Read the run with get_test_run.
• Every call writes one row to the workspace’s audit log (mcp.tool_call: the tool, the agent, the outcome, the credential id; never the text you sent) and each completed change one builder usage row under mcp:<tool> (a refused call or a replayed retry is not counted), apart from the call minutes the call service records.

​

Connected AI clients

• works on POST /v1/mcp and nothing else (any other route answers 403 forbidden);
• holds a fixed scope list: read gives the read tools’ scopes (call and conversation metadata only with call_records), draft adds only agents:write, test adds only tests:write, and build adds both. Owners can authorize drafting without test execution, or testing without draft edits. Explicit write access also adds agents:publish, knowledge:write, phone_numbers:read and phone_numbers:write. It never holds calls:write or a key scope. Existing keys are not upgraded;
• expires (90 days by default, at most 365) and is listed with when it was last used.

​

Write tools and a safe agent recipe

1. Connect with the narrowest access needed and call tools/list to discover available tools.
2. Use create_agent with a synthetic business name, then get_agent_draft and update_agent_draft with the returned revision. The App reads the same draft.
3. Add a text source with create_knowledge_source. Use the draft’s editable attachment fields to attach its collection. Uploading alone does not attach it or change the live agent.
4. Run run_agent_tests on the draft and read get_test_run. A failed or unavailable runner is not a passed test.
5. With explicit operator approval, use publish_agent_version to apply the draft and create an immutable version. save_agent_version instead compiles the already approved specification without applying unpublished edits. Neither tool promotes a production environment.
6. Run run_agent_simulations with chosen scenario keys and read get_agent_simulation until it finishes. The normal offline runner and its required local dependencies must be installed. Simulation results do not establish live-call proof.
7. Only after the normal telephony ownership and entitlement requirements are met, use bind_phone_number for an already owned number. Purchasing and releasing numbers are not MCP tools.

​

Build and test an agent from an outside AI client over REST

• Make another key. Only an owner signed in to the App can, so a key cannot mint a narrower one.
• Use the Builder. The Builder’s jobs (start, answer, review, apply) run inside the signed-in app. They are not on the API, and a key does not open them.

​

Clients

​

Retained candidate checks