Operate and report on a live account (MCP)

What you are looking at: the path for an agent that is connected to an account that already sends mail, and has to find out what it may do, report on how sending is going, and avoid the misreadings that waste a person's time. The answers at the bottom were each established from the code and a real read-only call, and say which. Connecting is covered in Hosted MCP; every tool named here is in the tool reference.

The journey

1. Find out who and what you are acting for. Call motorical_whoami. It returns the account, its plan and, over OAuth, the grant: the scopes it holds, the Motor Blocks it covers and what could still be added. Do this before anything else; do not infer scopes from the tool list. It needs no scope: any connection can call it.
2. List the Motor Blocks with motorical_list_motor_blocks and keep their ids. Most reporting tools need one.
3. Check standing against limits with motorical_get_account_rate_limits and motorical_get_rate_limits.
4. Read the results for a window with motorical_get_overview, then the per-day shape with motorical_get_daily_summary. Read how dates behave first.
5. Explain failures by cause. motorical_get_error_codes groups them; motorical_get_logs with smtpCode lists the messages behind a code or class.
6. Judge health with motorical_get_deliverability, motorical_get_reputation (a labelled delivery score, not a provider reputation) and motorical_get_anomalies, and check each sending domain with motorical_domain_health.
7. Report. Say which window you used, which Motor Blocks, and what you could not see because of a missing scope (step 1 tells you what the person can add and where). The tools return no "data as of" timestamp: the end of the window you asked for, or the time of your call when you gave none, is the freshest you can state.

Stop conditions: reporting never needs a write tool, so do not call one. A change to a Motor Block or a domain is a separate, confirmed action, covered by Journey B in the Agent Hub.

Answers, with their evidence

How does an agent know which scopes it holds?

Call motorical_whoami and read grant.scopes; grant is null when the call is not made over an OAuth grant. Any OAuth connection can call it whatever scopes it holds, and every server lists it, so a connection that holds only send:transactional can ask as well. The tool list otherwise narrows to what the grant covers, and a tool that is not listed still answers 403 insufficient_scope if called. The full picture of which tool needs which scope and which server lists it is the matrix.

Evidence: the grant-visibility rules in packages/motorical-mcp/src/grantVisibility.js (a tool is listed only when every scope it requires is covered, implied scopes counted; motorical_whoami requires none) and live calls on 2026-10-22 through the real hosted MCP server with temporary grants (since deleted) for the owner's own account. Before the fix, a grant holding only read:analytics saw the tool and was refused with 403 Missing required scope: config.read, and grants holding only send:transactional or only manage:webhooks never saw it. After the fix the same three grants all listed motorical_whoami, called it successfully and received their own scope in grant.scopes. A token carrying only logs.read that is not an OAuth grant is still refused with missing_scope, and one carrying config.read is accepted.

Does an array in to send one message or one per recipient?

One message. A request with several addresses in to makes a single send with a single id, delivered to every recipient; each recipient receives the same message and the To header shows the addresses as you wrote them, so recipients can see each other. cc and bcc belong to the same single message, and bcc is never named in a header. Delivery is tracked per recipient under that one id: motorical_wait_for_outcome waits until every recipient has a final outcome (recipients, expectedCount, allTerminal). If each person must get their own message, with no shared To line, make one send per recipient.

Evidence: backend/src/services/httpSendConverged.js stores one email_logs row whose metadata holds allRecipients: { to, cc, bcc }, and getRecipientOutcomes in services/messageOutcome/recipientOutcomes.js reads the expected recipients from that one row and the outcome of each from the delivery events. This was established from the code; no real multi-recipient send was made for this page.

How do dates behave in the analytics tools?

All times are UTC.

• to given as a date only (for example 2026-10-22) means the start of that day, 00:00:00 UTC, so that day's sends are not included. To include a whole day pass a time (2026-10-22T23:59:59Z) or the next day's date. The tool descriptions say "inclusive", which is true of the instant you give, not of the day.
• to omitted means now, so today up to the moment of the call is included.
• from omitted means as far back as your plan's retention allows; a from earlier than that is refused with 400.
• motorical_get_daily_summary counts days back from today and includes today (a partial day). Days with no sends are absent from the series: it is not zero-filled, so fewer rows than windowDays is normal, and an empty series means no sends. Each date is a UTC midnight timestamp.

Evidence: the route handlers for /overview and /daily-summary in backend/src/routes/public/index.js, and real calls on 2026-10-22 against a Motor Block with nine sends in the last seven days. With to omitted the overview counted 11 messages; with to=2026-10-22 it ended at 2026-10-22T00:00:00.000Z and counted 8; with to=2026-10-22T23:59:59Z it counted 11 again. daily-summary?days=7 returned two rows (21 and 22 October), not seven. The overview and daily summary cover different windows, so their totals are not meant to match each other.