MCP tools: Sandbox

The developer sandbox and free recipients. This page is the slice of the full MCP tool reference for the sandbox server (the other servers are listed on the hosted servers page). The main server carries every tool, so these entries apply there too. Failures use the shape described in MCP errors.

motorical_sandbox_status

Get developer sandbox status. Get developer sandbox status (domain, Motor Block, outbound lock, allowlist). Check data.stage to determine provisioning state: "not_started" (no sandbox yet — call motorical_sandbox_provision), "sandbox_active" (sandbox exists, outbound-locked), or "live" (converted to production, no lock). allowlist/caps are always present in the response regardless of stage — do not infer provisioning state from their presence. The allowlist is the EFFECTIVE list: sandbox recipients, link-confirmed recipients, the account address and the test sink, minus any address that clicked stop. domain.sandbox true means the Motorical-owned sandbox domain; domain.sandbox false means your own domain. outboundLocked true means real sends are limited to the allowlist, not that nothing can be sent; outboundLocked is null when no sandbox exists yet (nothing to lock). Requires OAuth scope: manage:sandbox (see motorical_whoami for what it allows).

Property	Value
Needs scope	manage:sandbox
Available on	Hosted servers: main, sandbox; the local server too
Acts on	The whole account (no Motor Block needed)
Not listed	Once the account is past the sandbox phase (a verified real domain and an active plan)
REST route	GET /api/public/v1/account/sandbox
Behaviour	Read-only; safe to repeat

No inputs.

Returns the JSON of the REST route above.

Example arguments (placeholders in angle brackets, required inputs only):

{}

motorical_sandbox_allowlist_request

Request sandbox allowlist addition. NOT AVAILABLE over hosted OAuth (dashboard session only): use motorical_free_recipient_add instead. Request to add a new recipient to the developer sandbox outbound allowlist. Sends a 6-digit confirmation code to that address (not the account owner) — call motorical_sandbox_allowlist_confirm with the code the recipient receives. Requires MOTORICAL_JWT. Requires OAuth scope: manage:sandbox (see motorical_whoami for what it allows). Needs a dashboard session, not OAuth — granting this scope does not make this tool callable over a hosted OAuth/Delegation connection.

Property	Value
Needs scope	manage:sandbox
Available on	Hosted servers: main, sandbox; the local server too
Acts on	See the description
Not listed	Never listed over OAuth (dashboard session only)
REST route	None
Behaviour	Changes data

Input	Type	Required	Meaning
email	string (email)	Yes	-

Returns the JSON of the REST route above.

Example arguments (placeholders in angle brackets, required inputs only):

{"email":"<email>"}

motorical_sandbox_allowlist_confirm

Confirm sandbox allowlist code. NOT AVAILABLE over hosted OAuth (dashboard session only): use motorical_free_recipient_add instead. Confirm a sandbox allowlist recipient using the 6-digit code sent by motorical_sandbox_allowlist_request. On success the address is added to the allowlist and can receive real (non-dryRun) sandbox sends. Requires MOTORICAL_JWT. Requires OAuth scope: manage:sandbox (see motorical_whoami for what it allows). Needs a dashboard session, not OAuth — granting this scope does not make this tool callable over a hosted OAuth/Delegation connection.

Property	Value
Needs scope	manage:sandbox
Available on	Hosted servers: main, sandbox; the local server too
Acts on	See the description
Not listed	Never listed over OAuth (dashboard session only)
REST route	None
Behaviour	Changes data

Input	Type	Required	Meaning
email	string (email)	Yes	-
code	string	Yes	-

Returns the JSON of the REST route above.

Example arguments (placeholders in angle brackets, required inputs only):

{"email":"<email>","code":"<code>"}

motorical_sandbox_provision

Provision developer sandbox. Provision the unpaid developer sandbox on a Motorical-owned .sandbox domain (Path 1: instant, no DNS) with an outbound-locked Motor Block. A Free account that adds and fully verifies its own domain (Path 2) gets a sandbox Motor Block on that domain automatically once DKIM and SPF pass, with no provisioning call, when automatic provisioning is enabled; if none appears on its own, call this tool (it creates one on the Motorical-owned domain). Over hosted OAuth, this NEVER returns credentials -- the response has credentialsAvailable:false instead. The new Motor Block is added to the live authorization and is immediately usable by explicit id, without refreshing an access token minted before provisioning. Credentials become available via a dashboard link after motorical_sandbox_convert. Only the local @motorical/mcp stdio server (dashboard-JWT auth) still returns mk_live_ once, since it is the customer's own long-running process on their own infrastructure -- securing whatever it returns is the customer's own responsibility on that path. Requires OAuth scope: manage:sandbox (see motorical_whoami for what it allows).

Property	Value
Needs scope	manage:sandbox
Available on	Hosted servers: main, sandbox; the local server too
Acts on	The whole account (no Motor Block needed)
Not listed	Once the account is past the sandbox phase (a verified real domain and an active plan)
REST route	POST /api/public/v1/account/sandbox/provision
Behaviour	Changes data

Input	Type	Required	Meaning
handle	string	No	-
channel	one of cli, agent, web	No	-

Returns the JSON of the REST route above.

Example arguments (placeholders in angle brackets, required inputs only):

{}

motorical_sandbox_convert

Convert sandbox to production. Convert sandbox Motor Block onto a verified customer domain (the target must be a verified real domain, never a .sandbox domain). A sandbox that already sits on your own verified domain converts onto that same domain, which needs no DNS change. Requires an active Motorical plan -- if none exists, this call throws with err.data.code === "subscription_required" and err.data.upgradeUrl naming where a human can subscribe; retry this same call once they have. If no sandbox exists yet (check motorical_sandbox_status first -- data.stage: "not_started"), call motorical_sandbox_provision instead; this endpoint returns 404 "No developer sandbox to convert" otherwise. The response always includes activeAuthMethod (the Motor Block's configured auth method -- "Password", "API Key", "OAuth 2.0", or "mTLS" -- read-only, changing it is dashboard-only). Conversion is a production identity transition: choose name/type or accept backend defaults; the SMTP username changes, so SMTP clients must be updated, while the existing SMTP password, API keys, and auth method remain unchanged. Over hosted OAuth it also includes credentialsLocation, a link to the dashboard where the customer can view or regenerate the actual credential value -- this tool never returns the raw value itself. Requires OAuth scope: manage:sandbox (see motorical_whoami for what it allows).

Property	Value
Needs scope	manage:sandbox
Available on	Hosted servers: main, sandbox; the local server too
Acts on	The whole account (no Motor Block needed)
Not listed	Once the account is past the sandbox phase (a verified real domain and an active plan)
REST route	POST /api/public/v1/account/sandbox/convert
Behaviour	Destructive: asks the person to confirm

Input	Type	Required	Meaning
domainId	string (uuid)	Yes	-
name	string	No	-
type	one of transactional, general_purpose	No	-
confirm	boolean	No	Supplied as true only after the human confirms the exact displayed action.

Returns the JSON of the REST route above.

Example arguments (placeholders in angle brackets, required inputs only):

{"domainId":"<domainId>"}

motorical_free_recipient_add

Ask a recipient to allow test email. Ask a person to allow test email from this account. Sends them a confirmation email with a link; THEY must open it and click the button, and this tool never confirms on their behalf. Until they confirm, a sandbox allowlist refuses sends to that address, and so do the non-sandbox Motor Blocks of a Free account (when Free enforcement is on); a paid account is not affected. Their address is then also allowed for the sandbox. A recipient who clicked "stop" cannot be re-requested; the response is identical either way. The response includes data.recipient with the address and its status (pending until they click, or confirmed if already confirmed); a person must still click the emailed link. Requires OAuth scope manage:recipients (separate from manage:sandbox; an existing sandbox authorization must be re-approved to include it). Requires OAuth scope: manage:recipients (see motorical_whoami for what it allows).

Property	Value
Needs scope	manage:recipients
Available on	Hosted servers: main, sandbox; the local server too
Acts on	The whole account (no Motor Block needed)
Not listed	Once the account is past the sandbox phase (a verified real domain and an active plan)
REST route	POST /api/public/v1/account/free-recipients
Behaviour	Changes data

Input	Type	Required	Meaning
email	string (email)	Yes	-

Returns the JSON of the REST route above.

Example arguments (placeholders in angle brackets, required inputs only):

{"email":"<email>"}

motorical_free_recipient_list

List allowed test recipients. List the addresses this account has asked to allow test email, with each status (pending, confirmed or stopped), the recipient limit and current usage. The hourly, daily and monthly numbers are the Free-plan caps for non-sandbox Motor Blocks (see limitsNote in the response); a sandbox Motor Block is governed by the sandbox caps shown in motorical_sandbox_status. Requires OAuth scope manage:recipients. Requires OAuth scope: manage:recipients (see motorical_whoami for what it allows).

Property	Value
Needs scope	manage:recipients
Available on	Hosted servers: main, sandbox; the local server too
Acts on	The whole account (no Motor Block needed)
Not listed	Once the account is past the sandbox phase (a verified real domain and an active plan)
REST route	GET /api/public/v1/account/free-recipients
Behaviour	Read-only; safe to repeat

No inputs.

Returns the JSON of the REST route above.

Example arguments (placeholders in angle brackets, required inputs only):

{}

motorical_free_recipient_remove

Remove a test recipient. Remove an address from this account's test recipients, by the id returned from motorical_free_recipient_list. Requires OAuth scope manage:recipients. Requires OAuth scope: manage:recipients (see motorical_whoami for what it allows).

Property	Value
Needs scope	manage:recipients
Available on	Hosted servers: main, sandbox; the local server too
Acts on	The whole account (no Motor Block needed)
Not listed	Once the account is past the sandbox phase (a verified real domain and an active plan)
REST route	DELETE /api/public/v1/account/free-recipients/{id}
Behaviour	Destructive: asks the person to confirm; safe to repeat

Input	Type	Required	Meaning
id	string (uuid)	Yes	Recipient id from motorical_free_recipient_list
confirm	boolean	No	Required: true. Confirms this destructive action.

Returns the JSON of the REST route above.

Example arguments (placeholders in angle brackets, required inputs only):

{"id":"<id>"}

motorical_whoami

Who am I (account, plan, grant). Who this connection is acting for: the account (id, owner email, name), its plan (name, status, hasSubscription), account.billing (price amount in minor units + currency + interval, trial end, current period end / next renewal date, cancelAtPeriodEnd and endsAt, this month's sends against the plan cap, and paymentMethod.status ok or failing; never invoices, receipts or card details; a field it cannot resolve is null with its reason under billing.unavailable) and, for an OAuth connection, the grant: the client, the scopes it holds, the Motor Blocks it covers, when it was granted, and canAdd (permissions it could still be given, with available:false where the plan does not allow it) plus addInDashboard, the page where the person adds them. Account-scoped: no Motor Block needed. grant is null when the call is not made over an OAuth grant. Over OAuth it needs no scope, so any connection can ask what it holds, and every server lists it. Use it instead of inferring scopes from the tool list.

Property	Value
Needs scope	No scope: any OAuth connection can call it
Available on	Hosted servers: main, transactional, analytics, domains, sandbox, webhooks, motorBlocks, communications; the local server too
Acts on	The whole account (no Motor Block needed)
Not listed	Never
REST route	GET /api/public/v1/account/whoami
Behaviour	Read-only; safe to repeat

Input	Type	Required	Meaning
motorBlockId	string (uuid)	No	Optional. This operation acts on the whole account, so a Motor Block is never needed; pass one only to record which block the call was made on behalf of.

Returns the JSON of the REST route above.

Example arguments (placeholders in angle brackets, required inputs only):

{}