Use personal MCP access

Personal MCP access is available to signed-in staff whose current role is organization_admin, organization_operator, partner_admin, or partner_operator. Platform Admin and client_tenant_user accounts cannot create or use a personal MCP token. A tenant API key is not an MCP credential.

Client validation status

Claude Code support is retained, but live validation is pending client testers. Codex CLI 0.153.4 was tested with the opt-in below; Codex desktop UI is unverified. ChatGPT web and OAuth connectors are not supported by this integration.

Codex compatibility check

Codex CLI 0.153.4, the latest stable release checked on 2026-09-07, connects with --enable mcp_2026_07_28. This opt-in is marked under development by Codex. It sends modern server/discover with matching 2026-07-28 headers and metadata. An actual disposable personal-token connection exposed the exact seven tools. Without the flag, Codex sends legacy initialize/2025-06-18 without the version header and receives HTTP 400 -32020, Header mismatch.

Do not manufacture protocol headers, add a translation proxy, or weaken the server. The server still accepts only 2026-07-28. Codex app behavior has not been separately tested; CLI results do not establish app or prompt-picker parity. The tested CLI workflow uses explicit business questions in the conversation, then validation and exact-argument review. It does not claim to select the server's guided prompt from a picker.

Configure an isolated disposable project .codex/config.toml, or use invocation-only -c overrides, without overwriting normal MCP settings. The evaluation used the existing supported ChatGPT login and temporary CLI overrides to disable unrelated configured MCP servers. An empty CODEX_HOME instead asks for its own sign-in; do not copy credential files into it. A subscription is not an API key. Keep the personal token in the named environment variable, not a file.

[mcp_servers.makeautomation]
url = "https://voice.makeautomation.ai/api/mcp"
bearer_token_env_var = "MAKEAUTOMATION_MCP_TOKEN"
default_tools_approval_mode = "prompt"

[mcp_servers.makeautomation.tools.create_agent]
approval_mode = "prompt"

[mcp_servers.makeautomation.tools.update_core_agent_configuration]
approval_mode = "prompt"

codex --version
codex --enable mcp_2026_07_28 --sandbox read-only --ask-for-approval on-request

These documented settings require real deny and approve testing before local acceptance. Review the full exact arguments in the displayed tool call; the permission dialog may abbreviate nested objects. For create, review branch_organization_id, tenant_id, idempotency_key, and proposal. For update, review those selected IDs plus agent_id, expected_version, and changes. Cancel if the full arguments are unavailable or not understood. Never use automatic approval or bypass modes. Anthropic metadata alone does not establish Codex consent. The operator's acceptance record must identify which actual cases passed; connection and validation alone are insufficient.

Connect Claude Code

These retained instructions are for the pending Claude Code client-tester evaluation, not a claim that live testing passed.

Use Claude Code 2.1.232 or later with its v2 MCP runtime. OAuth and the Claude web connector are deferred; this setup uses your own personal token. Create that token on Personal MCP access below, then set MAKEAUTOMATION_MCP_TOKEN privately in your local shell. Do not share it or put its value in a command, file, or screenshot.

claude --version
export MCP_SDK_GENERATION=v2
export MCP_PROTOCOL_NEGOTIATION=auto
claude mcp add-json makeautomation \
  '{"type":"http","url":"https://voice.makeautomation.ai/api/mcp","headers":{"Authorization":"Bearer ${MAKEAUTOMATION_MCP_TOKEN}"}}' \
  --scope local
claude mcp get makeautomation

Open Claude Code and run /mcp. Confirm a connected server with the seven tools listed below and the begin_guided_agent_intake prompt. Ask Claude to list your roots before selecting a root and tenant. Never infer IDs from names or combine permissions across roots.

The server accepts only revision 2026-07-28. Some hosted providers and gateways select an older runtime even on a new client. If your host cannot use the v2 runtime, connection fails and no tools become available. There is no legacy protocol or standalone event-stream fallback.

Every create and update requires a real interactive permission prompt. Review the exact arguments and approve or deny that call. The boolean anthropic/requiresUserInteraction: true prevents allow rules from skipping this prompt in supported clients. dontAsk denies locally; a non-interactive --permission-prompt-tool cannot approve it. Do not bypass these controls. Server authorization still applies even if another client ignores the hint.

Do not configure X-Forwarded-For in production clients. Trusted ingress adds the peer address. A missing or malformed trusted chain fails before bearer lookup. Limits are 30 requests per minute per trusted client address and 60 per active token per Dashboard process. On HTTP 429, wait for Retry-After; do not change the create key or automatically retry an update.

To disconnect locally:

claude mcp remove makeautomation --scope local
unset MAKEAUTOMATION_MCP_TOKEN MCP_SDK_GENERATION MCP_PROTOCOL_NEGOTIATION

Removing a local entry does not revoke the token. Revoke unused or exposed credentials through the self-service route; they have no automatic expiry.

Create the credential in the Dashboard

1. Sign in with your own eligible staff identity. Choose Personal MCP access beside Profile in the sidebar, or open /admin/mcp-settings.
2. Enter a Token name and choose Create token. Names are preserved, including pasted line endings, whitespace and duplicate or empty labels. Enter adds a line break; use Create token to submit. All valid Unicode, including emoji, combining marks and U+FFFD, stays exactly as entered. The create API rejects only null characters, U+0000, and unpaired UTF-16 surrogates within a string name with HTTP 400 MCP_TOKEN_NAME_INVALID, retryable: false, and details: {}. The message is "Token name must not contain null characters or unpaired Unicode surrogates". No token is generated, stored or audited for that rejection. Correct the name before submitting again; names are never trimmed, normalized, sanitized or deduplicated.
3. In Save your token now, deliberately choose Copy token and set MAKEAUTOMATION_MCP_TOKEN privately for your client. Do not record the value.
4. Choose Dismiss token after saving it privately. Dismissal, navigation, hiding the tab, or detected session loss clears the one-time value. The clipboard is not cleared automatically. Inventory cannot retrieve it.
5. Connect your AI client supplies the configured public endpoint, token-free Codex configuration, command, and a copyable first-use prompt.

Your tokens shows only your own inventory, with creation time, session version, and the current Active, Session invalidated, or Revoked status. Use Rotate or Revoke, then read and explicitly confirm the irreversible action. Rotation revokes the old token immediately and shows its replacement once. A session-invalidated token can be rotated using your new session.

A temporary background refresh failure leaves an already visible one-time token available to copy. Save it before dismissing it, then refresh the inventory. Detected session or access loss still clears the token immediately.

If the response is lost or uncertain, do not automatically create another token. Refresh inventory first. Revoke the newly issued token if you cannot recover its one-time value, or explicitly rotate it. An unavailable inventory is not proof that the operation failed. Sign in again if your session or access changes. Removing client configuration alone does not revoke a token.

Postman remains a supported operator path:

Create the credential in Postman

1. Import the collection for your role and run Authentication → Identity Login.
2. Open MCP → Create Personal MCP Token, set a name, and send the request.
3. Copy the returned token immediately into a private secret store or the empty mcp_token variable. The collection does not save it for you.
4. Run MCP → MCP Server Discover to verify authentication against /api/mcp.
5. Run MCP → List Accessible Organization Roots. Each item is exactly { branch_organization_id, organization_name, role, scope_mode }; the name, eligible role, and all_descendants or restricted scope mode are live. If the result has one item, use that stated ID. If it has several, choose one explicitly. An empty page means there is no current root access, so stop without requesting tenants.
6. Set branch_organization_id to the chosen stable UUID, then run MCP → List Accessible Tenants. Each item is exactly { tenant_id, name, organization_id, organization_name }, where the organization fields identify the tenant's current live owner. Select a returned tenant_id explicitly for later workflows.

The MCP endpoint accepts request bodies up to 4 MiB (4,194,304 bytes), measured from the actual streamed body before authentication.

Plaintext appears only in successful create and rotate responses, which are marked no-store. The server stores only a one-way hash and non-secret issuance metadata. Credentials have no automatic expiry. Do not put them in screenshots, Postman examples, logs, tickets, source files, shared environments, or URL parameters.

Review, rotate, or revoke credentials

• List Personal MCP Tokens returns only your credentials, newest first. It shows stable IDs, verbatim names, creation time, issuance session version, and exactly active, session_invalidated, or revoked; it never returns the credential, hash, expiry, or TTL.
• Set the non-secret mcp_token_id from that inventory, then use Rotate Personal MCP Token. The request body is optional and unrestricted in media type and shape up to 4 MiB (4,194,304 bytes). Only a valid UTF-8 JSON object with its own string-valued name property that is losslessly representable as PostgreSQL UTF-8 text renames the replacement, preserving that decoded JSON string exactly; all other under-limit bodies, bytes, or values—including malformed, unreadable, or unrecognized input—preserve the old name. Actual streamed bytes enforce the limit when Content-Length is absent, invalid, or understated. Oversized input returns 413 Payload too large with no-store before token lifecycle work or audit. The replacement is active at your current session version, the old credential is irreversibly revoked, and the new plaintext is shown once. A concurrent second rotation is rejected.
• Revoke Personal MCP Token is owner-only, irreversible, and safe to repeat. Unknown IDs and IDs owned by someone else receive the same response.

The hosted MCP protocol registers seven tools in fixed lexical order and one prompt: check_agent_readiness, create_agent, list_accessible_organization_roots, list_accessible_tenants, read_core_agent_configuration, update_core_agent_configuration, and validate_core_agent_proposal. Root and tenant discovery keeps duplicate names separate by stable ID and returns only active tenants after rechecking live identity, role, scope, capability, organization, and tenant state on every call. Root and tenant pages use opaque identity-bound cursors; tenant cursors also bind the selected root. Listing requires tenant:read, not tenant:operate, and returns no bearer, token hash, tenant API key, capability list, or cached authority. Discovery creates no mutation audit row.

Guide, validate, and create an agent

1. Select the begin_guided_agent_intake prompt. It is the only prompt exposed by the server.
2. Supply the chosen branch_organization_id and tenant_id. The server rechecks current tenant:read access and returns one message for Claude.
3. Confirm the tenant name and ID. Answer Claude's questions about the business, hours, supported tasks, escalation, tone, pronunciation and brand facts, greeting, model, voice, and turn behavior.
4. Claude calls validate_core_agent_proposal. The draft may be incomplete. Validation preserves your text, performs no write, and returns a deterministic issue list.
5. Review the exact proposed create_agent arguments. Claude must wait for explicit approval. Set a fresh opaque idempotency_key, then approve the call only when the selected root, tenant, name, prompt, and optional core settings are correct.
6. A successful call returns created and the saved core-agent configuration. Retrying the identical proposal with the same operator, tenant, and key returns replayed and the same agent. Reusing the key for different input returns IDEMPOTENCY_KEY_REUSED; retrying after that agent was deleted returns IDEMPOTENCY_RESULT_GONE.

Creation rechecks current tenant:operate authority inside the transaction that reserves and writes the agent. Semantic validation runs before any idempotency hash, reservation, or write. Omitted optional core settings use the existing defaults; supplied empty strings, whitespace, line endings, and false values are preserved. vad_stop_secs accepts 0.1 through 5; zero returns OUT_OF_RANGE. The agent, initial prompt version, required audit, and completed request record commit together. A regional mirror failure is reported separately with primary_committed: true; it does not undo the primary agent.

Do not retry with a new key after an ambiguous client/network failure. Retry the exact proposal with the same key so the server can return the committed result.

Do not provide secrets, credentials, phone or PBX settings, integration values, calls, transcripts, analytics, or knowledge documents during intake or create. The create input does not accept tenant lifecycle, STT, activation, call duration, arbitrary tools, integrations, restore IDs, or legacy audit policy. The server does not store the interview, a transcript, a template, elicitation data, or request state. Declining or cancelling before the tool call has no server-side effect.

Validation issues use only REQUIRED, EMPTY_REQUIRED, STRING_TOO_LONG, INVALID_TEXT, OUT_OF_RANGE, UNSUPPORTED_PROVIDER, and INVALID_VOICE_ID. U+0000 returns INVALID_TEXT because PostgreSQL text cannot store it; other accepted text remains verbatim. Raw unsupported provider text reaches semantic validation instead of being rewritten or rejected as a malformed tool request.

Read and update an existing agent

1. Select the exact root, tenant, and agent ID. Call read_core_agent_configuration to see the current version, exact stored values, and separate runtime effective values. Null timestamps and legacy strings are returned unchanged. Only stored is_active: true admits calls; null and false do not. An empty or null greeting uses the audible default Hello! How can I help you today? without changing its stored value.
2. Propose only the core leaves you want to replace. Omitted leaves preserve their existing values, including nulls and legacy text. Supplied leaves use current validation limits. A patch with no leaves returns EMPTY_PATCH. Update text containing unpaired UTF-16 surrogates returns INVALID_TEXT rather than saving replacement characters. Valid Unicode remains verbatim.
3. Review the exact root, tenant, agent, expected_version, and changes. Give explicit approval before update_core_agent_configuration. The tool advertises a destructive update and requires interactive approval in a supported client, just like creation.
4. Success returns primary_committed: true, the new configuration and version, and a separate regional mirror outcome. Even a same-value named update consumes the version. Only changed prompt text appends prompt history.
5. VERSION_CONFLICT means the version was already consumed. Read again, review the differences, and obtain renewed approval. Never retry automatically or assume that a failed mirror rolled back the primary update.

For create, replay and update, cancellation observed before the database COMMIT is sent rolls back that transaction and skips mirroring. Once COMMIT is sent, the result may be committed or uncertain even if you cancel or disconnect. Cancellation never deletes the agent or restores old values after dispatch. For an ambiguous create, approve a retry with the identical key and proposal. For an ambiguous update, read the saved state and seek fresh approval before another change. Do not retry the old version automatically.

Restore remains a staff Dashboard operation, not an MCP tool. Restoring the same prompt appends history without changing the configuration version; restoring different text advances it once. MCP cannot change activation, STT, duration, tools, integrations, or tenant lifecycle.

When access stops working

Every request rechecks the live identity. A password reset or another session security change, identity disablement, authentication-mode change, or loss of the final eligible role invalidates the credential immediately. The endpoint returns the same authentication error for these cases and for an unknown credential.

Check core readiness

Call check_agent_readiness with the exact selected root, tenant, and agent IDs. It rechecks live read access and returns status, version, ordered checks, and regional_configuration. This is core configuration evidence, not live-call readiness. It does not check phone routing, PBX, provider credentials, or integrations.

The first check requires stored is_active: true. Null or false means not ready. The remaining checks evaluate name/prompt presence, effective greeting, voice, model, and turn behavior. Null or empty greeting uses the existing audible default. Legacy text is not rewritten or rejected just because it exceeds current write limits.

Primary tenants report regional not_required without a regional connection. Sydney reports current only when versions and all stored core fields match. regional_row_missing, version_mismatch, field_mismatch, unavailable, and unsupported_region force not_ready. Version mismatch takes precedence over field mismatch; field names are sorted and compare stored nulls and text exactly. Readiness compares full stored versions, even when large version numbers round to the same value in a client. Use the regional status rather than comparing displayed numbers yourself. Creation and update timestamps do not affect readiness.

Checking readiness never writes, audits, mirrors, or repairs anything. A mutation's mirror outcome is separate from current readiness. After a partial create result, retry only the identical proposal and key to retry its full mirror. After an update, do not reuse a stale version. Ask an operator to use the existing Data Plane repair action, then check readiness again.