MCP tools: Domains

Sending domains, DNS records and authentication health. This page is the slice of the full MCP tool reference for the domains 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_domain_add

Add a customer domain. Add a customer domain. Returns verification DNS instructions. For cname_managed DKIM publish the CNAME in verification.records.dkim / dnsRecords (not a TXT p= key). On 409 (domain already registered), call motorical_domain_list first to check whether it is already on this account before asking the user to resolve the conflict. A Free account may have one domain; adding another returns free_domain_limit with a nextAction. Over hosted OAuth it needs the manage:domains scope; the local server uses MOTORICAL_JWT. Requires OAuth scope: manage:domains (see motorical_whoami for what it allows).

Property	Value
Needs scope	manage:domains
Available on	Hosted servers: main, domains; the local server too
Acts on	The whole account (no Motor Block needed)
Not listed	When the connection does not hold the scope (the narrow servers hide it; the main server lists it marked "Needs permission")
REST route	POST /api/public/v1/domains
Behaviour	Changes data

Input	Type	Required	Meaning
domain	string	Yes	-
verificationMethod	one of dns, email	No	-
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.
idempotencyKey	string	No	Optional. Pass the same value on a retry to get the exact original response back, instead of a duplicate.

Returns the JSON of the REST route above.

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

{"domain":"<domain>"}

motorical_domain_list

List account domains. List domains already on this account — id, domain, verified, DNS auth flags. Call this before motorical_domain_add on a 409 conflict to self-diagnose whether the domain is already yours (proceed with the existing id) or genuinely owned by someone else (stop, do not guess). Over hosted OAuth it needs the read:domains scope; the local server uses MOTORICAL_JWT. Requires OAuth scope: read:domains (see motorical_whoami for what it allows).

Property	Value
Needs scope	read:domains
Available on	Hosted servers: main, domains; the local server too
Acts on	The whole account (no Motor Block needed)
Not listed	When the connection does not hold the scope (the narrow servers hide it; the main server lists it marked "Needs permission")
REST route	GET /api/public/v1/domains
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):

{}

motorical_domain_get

Get one account domain. One domain on this account by id: verified, DNS auth flags, DKIM mode, created. Read-only; no keys or tokens. Over hosted OAuth it needs the read:domains scope. Requires OAuth scope: read:domains (see motorical_whoami for what it allows).

Property	Value
Needs scope	read:domains
Available on	Hosted servers: main, domains; the local server too
Acts on	The whole account (no Motor Block needed)
Not listed	When the connection does not hold the scope (the narrow servers hide it; the main server lists it marked "Needs permission")
REST route	GET /api/public/v1/domains/{id}
Behaviour	Read-only; safe to repeat

Input	Type	Required	Meaning
domainId	string (uuid)	Yes	-
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):

{"domainId":"<domainId>"}

motorical_domain_dns_records

Get domain DNS records. The DNS records to publish for one domain, with what each is for. Pass lookup:true to also check what DNS currently answers (slower: live lookups). Read-only. Over hosted OAuth it needs the read:domains scope. Requires OAuth scope: read:domains (see motorical_whoami for what it allows).

Property	Value
Needs scope	read:domains
Available on	Hosted servers: main, domains; the local server too
Acts on	The whole account (no Motor Block needed)
Not listed	When the connection does not hold the scope (the narrow servers hide it; the main server lists it marked "Needs permission")
REST route	GET /api/public/v1/domains/{id}/dns-records
Behaviour	Read-only; safe to repeat

Input	Type	Required	Meaning
domainId	string (uuid)	Yes	-
lookup	boolean	No	Also run live DNS lookups for each record (default false)
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):

{"domainId":"<domainId>"}

motorical_domain_health

Get domain health by domain. Email-authentication health of ONE domain by id: SPF, DKIM, DMARC, status, issues, and whether the answer is cached (source). Works for a domain that has no Motor Block yet. Same shape as motorical_get_domain_health, which answers for the domain attached to one Motor Block. Pass refresh:true for a live DNS check (slower). A result with source "cache_stale" or refreshing:true is the last stored check (cacheAgeSeconds says how old; can be days): a recheck has started, so read again in about ten seconds or pass refresh:true. dmarc.policy is not reported yet (always null); dmarc.configured says whether a record exists. Read-only. Over hosted OAuth it needs the read:domains scope. Requires OAuth scope: read:domains (see motorical_whoami for what it allows).

Property	Value
Needs scope	read:domains
Available on	Hosted servers: main, domains; the local server too
Acts on	The whole account (no Motor Block needed)
Not listed	When the connection does not hold the scope (the narrow servers hide it; the main server lists it marked "Needs permission")
REST route	GET /api/public/v1/domains/{id}/health
Behaviour	Read-only; safe to repeat

Input	Type	Required	Meaning
domainId	string (uuid)	Yes	-
refresh	boolean	No	Run a live DNS check instead of serving the cache (default false)
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):

{"domainId":"<domainId>"}

motorical_domain_verify

Verify domain ownership. Verify domain ownership and refresh DKIM/SPF/DMARC send-readiness flags. Requires confirm:true — this call is destructive/consequential. Returns sendReady. Over hosted OAuth it needs the manage:domains scope; the local server uses MOTORICAL_JWT. Requires OAuth scope: manage:domains (see motorical_whoami for what it allows).

Property	Value
Needs scope	manage:domains
Available on	Hosted servers: main, domains; the local server too
Acts on	The whole account (no Motor Block needed)
Not listed	When the connection does not hold the scope (the narrow servers hide it; the main server lists it marked "Needs permission")
REST route	POST /api/public/v1/domains/{id}/verify
Behaviour	Destructive: asks the person to confirm

Input	Type	Required	Meaning
domainId	string (uuid)	Yes	-
method	one of dns, email	No	-
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.
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):

{"domainId":"<domainId>"}

motorical_domain_check_dns

Live-check domain DNS. Live-check DKIM/SPF/DMARC and persist dkim_configured/spf_configured. Required before /v1/send when ownership is verified but send returns DOMAIN_DNS_INCOMPLETE. Over hosted OAuth it needs the manage:domains scope; the local server uses MOTORICAL_JWT. Requires OAuth scope: manage:domains (see motorical_whoami for what it allows).

Property	Value
Needs scope	manage:domains
Available on	Hosted servers: main, domains; the local server too
Acts on	The whole account (no Motor Block needed)
Not listed	When the connection does not hold the scope (the narrow servers hide it; the main server lists it marked "Needs permission")
REST route	POST /api/public/v1/domains/{id}/check-dns
Behaviour	Changes data; safe to repeat

Input	Type	Required	Meaning
domainId	string (uuid)	Yes	-
recordType	one of dkim, spf, dmarc, mx	No	-
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):

{"domainId":"<domainId>"}

motorical_get_onboarding_state

Get onboarding/account state. Where this account stands right now: stage, whether it can actually send (ready_to_send), what's blocking it, and the one next tool to call to move forward (GET /api/public/v1/account/state). Account-scoped: no Motor Block needed. Each blocker carries humanRequired (a person must act) and, where there is one, a nextAction. For an account with no plan and no domain the response also lists two onboarding options, own_domain and sandbox_domain, and a choose rule for picking between them: state the choice and the reason, and the person may override. Confirming recipients by emailed link needs the manage:recipients scope; an existing authorization must be re-approved to include it. Requires OAuth scope: read:domains (see motorical_whoami for what it allows).

Property	Value
Needs scope	read:domains
Available on	Hosted servers: main, domains; the local server too
Acts on	The whole account (no Motor Block needed)
Not listed	When the connection does not hold the scope (the narrow servers hide it; the main server lists it marked "Needs permission")
REST route	GET /api/public/v1/account/state
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):

{}

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

{}

motorical_get_config

Get Motor Block config. Configuration of one Motor Block — its sending domain, limits (as configured) and effectiveLimits (what is enforced now: dailyVolume, hourlyRate and burstLimit, the lower of configured and any reputation throttle, with defaults filled in; burstLimit is a short-window cap that applies to every block even when not configured), delivery settings, and activeAuthMethod ("Password"/"API Key"/"OAuth 2.0"/"mTLS", read-only -- changing it is dashboard-only). Requires OAuth scope: read:domains (see motorical_whoami for what it allows).

Property	Value
Needs scope	read:domains
Available on	Hosted servers: main, domains; the local server too
Acts on	One Motor Block (the motorBlockId input)
Not listed	When the connection does not hold the scope (the narrow servers hide it; the main server lists it marked "Needs permission")
REST route	GET /api/public/v1/motor-blocks/{id}/config
Behaviour	Read-only; safe to repeat

Input	Type	Required	Meaning
motorBlockId	string (uuid)	No	Required when the authorization covers more than one Motor Block

Returns the JSON of the REST route above.

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

{}

motorical_get_domain_health

Get domain health. DNS and email-authentication health for the Motor Block's sending domain — SPF, DKIM, DMARC, MX. This is a set-up status, not a score, and it is separate from the delivery reputation score (motorical_get_reputation), which measures delivery outcomes. A result with source "cache_stale" or refreshing:true is the last stored check (cacheAgeSeconds says how old; can be days): a recheck has started, so read again in about ten seconds or pass refresh:true. dmarc.policy is not reported yet (always null); dmarc.configured says whether a record exists. Requires OAuth scope: read:domains (see motorical_whoami for what it allows).

Property	Value
Needs scope	read:domains
Available on	Hosted servers: main, domains; the local server too
Acts on	One Motor Block (the motorBlockId input)
Not listed	When the connection does not hold the scope (the narrow servers hide it; the main server lists it marked "Needs permission")
REST route	GET /api/public/v1/motor-blocks/{id}/domain-health
Behaviour	Read-only; safe to repeat

Input	Type	Required	Meaning
motorBlockId	string (uuid)	No	Required when the authorization covers more than one Motor Block
refresh	boolean	No	Re-run the live DNS checks now instead of returning the last cached result

Returns the JSON of the REST route above.

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

{}