@motorical/mcp 1.2.0 → 1.3.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@motorical/mcp",
-  "version": "1.2.0",
-  "description": "MCP server for Motorical transactional email API \u2014 dry-run/send, mint public tokens, list Motor Blocks, inspect delivery events",
+  "version": "1.3.0",
+  "description": "MCP server for Motorical transactional email API — dry-run/send, mint public tokens, list Motor Blocks, inspect delivery events",
   "type": "module",
   "bin": {
     "motorical-mcp": "./src/index.js"

package/src/client.js

@@ -3,6 +3,7 @@
  * Auth rules match docs.motorical.com (mk_live_ → /v1/send; ak_live_ → mint bearer).
  */
 
+import { AsyncLocalStorage } from 'node:async_hooks';
 import {
   loadCredentials, saveCredentials, isExpired, discover, refreshTokens,
 } from './oauth.js';
@@ -10,6 +11,18 @@ import {
 const DEFAULT_API_BASE = 'https://api.motorical.com';
 const DEFAULT_DOCS_BASE = 'https://docs.motorical.com';
 
+/**
+ * Per-call forced-auth context for withAuth()/request(). This is a module-
+ * level AsyncLocalStorage, not an instance field: a plain `this._forcedAuth`
+ * field set-and-restored around an await would be shared mutable state on
+ * the client instance, so two overlapping withAuth() calls on the same
+ * client (e.g. two concurrent tool calls sharing one MotoricalClient) could
+ * stomp each other's headers depending on scheduling. ALS binds the
+ * override to the async call chain that set it, so concurrent chains never
+ * observe each other's context regardless of interleaving.
+ */
+const forcedAuthStorage = new AsyncLocalStorage();
+
 export function loadConfig(env = process.env) {
   return {
     apiBaseUrl: (env.MOTORICAL_API_BASE_URL || DEFAULT_API_BASE).replace(/\/$/, ''),
@@ -86,9 +99,22 @@ export class MotoricalClient {
     return this.config.mkApiKey;
   }
 
-  async request(method, path, { headers = {}, body, apiKey, bearer } = {}) {
+  /** Runs `fn` with these headers forced onto every request it makes. */
+  async withAuth(headers, fn) {
+    return forcedAuthStorage.run(headers, fn);
+  }
+
+  async request(method, path, opts = {}) {
+    const { headers = {}, body } = opts;
+    let { apiKey, bearer } = opts;
     const url = `${this.config.apiBaseUrl}${path.startsWith('/') ? path : `/${path}`}`;
     const h = { Accept: 'application/json', ...headers };
+    const forcedAuth = forcedAuthStorage.getStore();
+    if (forcedAuth) {
+      Object.assign(h, forcedAuth);
+      apiKey = undefined;
+      bearer = undefined;
+    }
     if (apiKey) h.Authorization = `ApiKey ${apiKey}`;
     if (bearer) h.Authorization = `Bearer ${bearer}`;
     if (body !== undefined) h['Content-Type'] = 'application/json';
@@ -166,6 +192,144 @@ export class MotoricalClient {
     return `${path}${sep}motorBlockId=${encodeURIComponent(id)}`;
   }
 
+  /**
+   * The account-scoped counterpart to _scoped, for operations acting on the
+   * ACCOUNT rather than on one Motor Block (domain management, listing the
+   * blocks themselves). The backend mounts those routes with
+   * { accountScoped: true } and reads only the token's user, so a block is
+   * passed through when the caller has one and omitted when not — never
+   * demanded, and never a reason to throw.
+   */
+  _accountPath(path, motorBlockId) {
+    if (!this.hasOAuthSession()) return path;
+    const id = motorBlockId || this.config.motorBlockId;
+    if (!id) return path;
+    const sep = path.includes('?') ? '&' : '?';
+    return `${path}${sep}motorBlockId=${encodeURIComponent(id)}`;
+  }
+
+  /**
+   * Query string from a params object, skipping anything the caller didn't
+   * supply. Returns '' when nothing survives, so it composes with _scoped()
+   * and _accountPath() — both of which detect an existing '?' and switch to
+   * '&' when appending motorBlockId.
+   */
+  _qs(params = {}) {
+    const q = new URLSearchParams();
+    for (const [k, v] of Object.entries(params)) {
+      if (v === undefined || v === null || v === '') continue;
+      q.set(k, String(v));
+    }
+    const s = q.toString();
+    return s ? `?${s}` : '';
+  }
+
+  async getOverview({ motorBlockId, from, to } = {}) {
+    const bearer = await this.getBearer({ motorBlockId });
+    const path = `/api/public/v1/motor-blocks/${encodeURIComponent(motorBlockId)}/overview`;
+    return this.request('GET', this._scoped(path + this._qs({ from, to }), motorBlockId), { bearer });
+  }
+
+  async getDailySummary({ motorBlockId, days } = {}) {
+    const bearer = await this.getBearer({ motorBlockId });
+    const path = `/api/public/v1/motor-blocks/${encodeURIComponent(motorBlockId)}/daily-summary`;
+    return this.request('GET', this._scoped(path + this._qs({ days }), motorBlockId), { bearer });
+  }
+
+  async getMetrics({ motorBlockId, from, to, interval } = {}) {
+    const bearer = await this.getBearer({ motorBlockId });
+    const path = `/api/public/v1/motor-blocks/${encodeURIComponent(motorBlockId)}/metrics`;
+    return this.request('GET', this._scoped(path + this._qs({ from, to, interval }), motorBlockId), { bearer });
+  }
+
+  async getDeliverability({ motorBlockId, from, to, limit } = {}) {
+    const bearer = await this.getBearer({ motorBlockId });
+    const path = `/api/public/v1/motor-blocks/${encodeURIComponent(motorBlockId)}/deliverability`;
+    return this.request('GET', this._scoped(path + this._qs({ from, to, limit }), motorBlockId), { bearer });
+  }
+
+  async getReputation({ motorBlockId } = {}) {
+    const bearer = await this.getBearer({ motorBlockId });
+    const path = `/api/public/v1/motor-blocks/${encodeURIComponent(motorBlockId)}/reputation`;
+    return this.request('GET', this._scoped(path, motorBlockId), { bearer });
+  }
+
+  async getAnomalies({ motorBlockId } = {}) {
+    const bearer = await this.getBearer({ motorBlockId });
+    const path = `/api/public/v1/motor-blocks/${encodeURIComponent(motorBlockId)}/anomalies`;
+    return this.request('GET', this._scoped(path, motorBlockId), { bearer });
+  }
+
+  async getProviders({ motorBlockId, from, to, limit } = {}) {
+    const bearer = await this.getBearer({ motorBlockId });
+    const path = `/api/public/v1/motor-blocks/${encodeURIComponent(motorBlockId)}/providers`;
+    return this.request('GET', this._scoped(path + this._qs({ from, to, limit }), motorBlockId), { bearer });
+  }
+
+  async getErrorCodes({ motorBlockId, from, to, limit } = {}) {
+    const bearer = await this.getBearer({ motorBlockId });
+    const path = `/api/public/v1/motor-blocks/${encodeURIComponent(motorBlockId)}/error-codes`;
+    return this.request('GET', this._scoped(path + this._qs({ from, to, limit }), motorBlockId), { bearer });
+  }
+
+  async getRateLimits({ motorBlockId } = {}) {
+    const bearer = await this.getBearer({ motorBlockId });
+    const path = `/api/public/v1/motor-blocks/${encodeURIComponent(motorBlockId)}/rate-limits`;
+    return this.request('GET', this._scoped(path, motorBlockId), { bearer });
+  }
+
+  async getConfig({ motorBlockId } = {}) {
+    const bearer = await this.getBearer({ motorBlockId });
+    const path = `/api/public/v1/motor-blocks/${encodeURIComponent(motorBlockId)}/config`;
+    return this.request('GET', this._scoped(path, motorBlockId), { bearer });
+  }
+
+  // refresh is sent only when true: the route reads it as "re-run the live DNS
+  // check now", so refresh=false is not the same request as omitting it.
+  async getDomainHealth({ motorBlockId, refresh } = {}) {
+    const bearer = await this.getBearer({ motorBlockId });
+    const path = `/api/public/v1/motor-blocks/${encodeURIComponent(motorBlockId)}/domain-health`;
+    const qs = this._qs({ refresh: refresh === true ? 'true' : undefined });
+    return this.request('GET', this._scoped(path + qs, motorBlockId), { bearer });
+  }
+
+  // Account-wide: the route is mounted { accountScoped: true } and reads only
+  // the token's user, so _accountPath omits the block rather than throwing.
+  // Using _scoped() here would demand a Motor Block for an account-wide route.
+  async getAccountRateLimits({ motorBlockId } = {}) {
+    const bearer = await this.getBearer({ motorBlockId });
+    return this.request(
+      'GET',
+      this._accountPath('/api/public/v1/account/rate-limits', motorBlockId),
+      { bearer }
+    );
+  }
+
+  async getLogs({
+    motorBlockId, from, to, currentOutcome, query, limit, cursor, includePII,
+  } = {}) {
+    const bearer = await this.getBearer({ motorBlockId });
+    const path = `/api/public/v1/motor-blocks/${encodeURIComponent(motorBlockId)}/logs`;
+    const qs = this._qs({
+      from, to, currentOutcome, query, limit, cursor,
+      includePII: includePII === true ? 'true' : undefined,
+    });
+    return this.request('GET', this._scoped(path + qs, motorBlockId), { bearer });
+  }
+
+  // GET /messages is a LOOKUP, not a listing: it 400s without an exact
+  // smtpMessageId and resolves at most one match. This is a second lookup key
+  // alongside getMessage()'s internal UUID, never a way to browse.
+  async getMessageBySmtpId({ smtpMessageId, motorBlockId, includePII } = {}) {
+    if (!smtpMessageId) throw new Error('smtpMessageId is required');
+    const bearer = await this.getBearer({ motorBlockId });
+    const qs = this._qs({
+      smtpMessageId,
+      includePII: includePII === true ? 'true' : undefined,
+    });
+    return this.request('GET', this._scoped(`/api/public/v1/messages${qs}`, motorBlockId), { bearer });
+  }
+
   async getBearer({ motorBlockId, forceRefresh = false } = {}) {
     // An OAuth grant supersedes minted public tokens entirely — no ak_live_ key
     // and no dashboard JWT needed.
@@ -182,7 +346,7 @@ export class MotoricalClient {
 
   async listMotorBlocks({ motorBlockId } = {}) {
     const bearer = await this.getBearer({ motorBlockId });
-    return this.request('GET', this._scoped('/api/public/v1/motor-blocks', motorBlockId), { bearer });
+    return this.request('GET', this._accountPath('/api/public/v1/motor-blocks', motorBlockId), { bearer });
   }
 
   async sendEmail(payload) {
@@ -197,6 +361,7 @@ export class MotoricalClient {
       confirmRealSend = false,
       idempotencyKey,
       headers: customHeaders,
+      motorBlockId: _motorBlockId, // never in the body — see sendPath below
       ...rest
     } = payload;
 
@@ -310,44 +475,85 @@ export class MotoricalClient {
     });
   }
 
-  async domainList() {
-    // An OAuth grant reads the scoped public endpoint. It cannot use
-    // /api/domains: that route is behind the dashboard-session middleware,
-    // which also guards billing and account settings.
-    const oauthToken = await this.oauthAccessToken();
-    if (oauthToken) {
-      // Domains are account-wide, but authenticatePublic keeps MCP grants
-      // strictly block-bound rather than silently choosing one, so the
-      // selector travels here too. The endpoint scopes by user, not by block.
-      return this.request('GET', this._scoped('/api/public/v1/domains'), { bearer: oauthToken });
+  // These four target the public API the same way listMotorBlocks/getMessage
+  // do — never branching on oauthAccessToken() to pick a URL. That branch was
+  // the bug: it's null for a delegated call by design (no stored session,
+  // auth travels per-call instead), so every one of these calls fell through
+  // to /api/domains, which rejects a Delegation header outright.
+  //
+  // One narrow exception, preserved on purpose: a dashboard-JWT-only caller
+  // (no OAuth session, MOTORICAL_JWT set directly) with NO motor block
+  // configured yet — the state a brand-new customer is in before their first
+  // Motor Block exists, but domains are account-wide and this account may
+  // already need one added. mintPublicToken() hard-requires a motorBlockId
+  // it doesn't have; /api/domains doesn't need one at all. A delegated call
+  // never hits this branch — resolveBlock() in delegatedClient.js always
+  // supplies a real motorBlockId before any of these run.
+  hasNoBlockToScopeAPublicToken(motorBlockId) {
+    // _delegated is set by delegatedClient.js's callView. A delegated call is
+    // never the legacy dashboard-JWT caller this fallback exists for: its
+    // dashboardJwt is a placeholder, not a credential, so taking this branch
+    // means authenticating the dashboard route with the string
+    // 'mcp-delegated' — a guaranteed 401. This used to be unreachable because
+    // resolveBlock() always supplied a block; account-scoped tools now supply
+    // none, so the guard has to be explicit. Found live 2026-09-02.
+    if (this._delegated) return false;
+    return !(motorBlockId || this.config.motorBlockId) && !this.hasOAuthSession();
+  }
+
+  async domainList({ motorBlockId } = {}) {
+    if (this.hasNoBlockToScopeAPublicToken(motorBlockId) && this.config.dashboardJwt) {
+      return this.request('GET', '/api/domains', { bearer: this.requireDashboardJwt() });
     }
-    return this.request('GET', '/api/domains', {
-      bearer: this.requireDashboardJwt()
-    });
+    const bearer = await this.getBearer({ motorBlockId });
+    return this.request('GET', this._accountPath('/api/public/v1/domains', motorBlockId), { bearer });
   }
 
-  async domainAdd({ domain, verificationMethod = 'dns' } = {}) {
+  async domainAdd({ domain, verificationMethod = 'dns', motorBlockId } = {}) {
     if (!domain) throw new Error('domain is required');
-    return this.request('POST', '/api/domains', {
-      bearer: this.requireDashboardJwt(),
+    if (this.hasNoBlockToScopeAPublicToken(motorBlockId) && this.config.dashboardJwt) {
+      return this.request('POST', '/api/domains', {
+        bearer: this.requireDashboardJwt(),
+        body: { domain, verificationMethod }
+      });
+    }
+    const bearer = await this.getBearer({ motorBlockId });
+    return this.request('POST', this._accountPath('/api/public/v1/domains', motorBlockId), {
+      bearer,
       body: { domain, verificationMethod }
     });
   }
 
-  async domainVerify({ domainId, method = 'dns' } = {}) {
+  async domainVerify({ domainId, method = 'dns', motorBlockId } = {}) {
     if (!domainId) throw new Error('domainId is required');
-    return this.request('POST', `/api/domains/${encodeURIComponent(domainId)}/verify`, {
-      bearer: this.requireDashboardJwt(),
-      body: { method }
-    });
+    if (this.hasNoBlockToScopeAPublicToken(motorBlockId) && this.config.dashboardJwt) {
+      return this.request('POST', `/api/domains/${encodeURIComponent(domainId)}/verify`, {
+        bearer: this.requireDashboardJwt(),
+        body: { method }
+      });
+    }
+    const bearer = await this.getBearer({ motorBlockId });
+    return this.request(
+      'POST',
+      this._accountPath(`/api/public/v1/domains/${encodeURIComponent(domainId)}/verify`, motorBlockId),
+      { bearer, body: { method } }
+    );
   }
 
-  async domainCheckDns({ domainId, recordType } = {}) {
+  async domainCheckDns({ domainId, recordType, motorBlockId } = {}) {
     if (!domainId) throw new Error('domainId is required');
-    return this.request('POST', `/api/domains/${encodeURIComponent(domainId)}/check-dns`, {
-      bearer: this.requireDashboardJwt(),
-      body: recordType ? { recordType } : {}
-    });
+    if (this.hasNoBlockToScopeAPublicToken(motorBlockId) && this.config.dashboardJwt) {
+      return this.request('POST', `/api/domains/${encodeURIComponent(domainId)}/check-dns`, {
+        bearer: this.requireDashboardJwt(),
+        body: recordType ? { recordType } : {}
+      });
+    }
+    const bearer = await this.getBearer({ motorBlockId });
+    return this.request(
+      'POST',
+      this._accountPath(`/api/public/v1/domains/${encodeURIComponent(domainId)}/check-dns`, motorBlockId),
+      { bearer, body: recordType ? { recordType } : {} }
+    );
   }
 
   async sandboxAllowlistRequest({ email } = {}) {

package/src/server.js

@@ -1,8 +1,11 @@
+import { readFileSync } from 'node:fs';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import { MotoricalClient, loadConfig } from './client.js';
 
-const PACKAGE_VERSION = '1.1.3';
+const PACKAGE_VERSION = JSON.parse(
+  readFileSync(new URL('../package.json', import.meta.url))
+).version;
 
 function jsonResult(data, { isError = false } = {}) {
   return {
@@ -34,7 +37,19 @@ export function createMotoricalMcpServer(options = {}) {
     version: PACKAGE_VERSION
   });
 
-  server.registerTool(
+  // The stdio/CLI entrypoint (index.js) calls this with no allowedTools and
+  // gets every tool, unaffected. The HTTP resource server (http.js) passes
+  // the connected server's own tool list: without this, tools/list would
+  // advertise every tool on every path — e.g. motorical_send_email on the
+  // analytics-only server — even though calling it there would be refused.
+  // The advertisement must match what's actually callable.
+  const allowedTools = options.allowedTools || null;
+  function registerTool(name, config, cb) {
+    if (allowedTools && !allowedTools.includes(name)) return;
+    server.registerTool(name, config, cb);
+  }
+
+  registerTool(
     'motorical_get_send_status',
     {
       description:
@@ -50,7 +65,7 @@ export function createMotoricalMcpServer(options = {}) {
     }
   );
 
-  server.registerTool(
+  registerTool(
     'motorical_mint_public_token',
     {
       description:
@@ -72,13 +87,13 @@ export function createMotoricalMcpServer(options = {}) {
     }
   );
 
-  server.registerTool(
+  registerTool(
     'motorical_list_motor_blocks',
     {
       description:
         'List Motor Blocks (isolated sending streams) visible to a Public API bearer token (auto-mints with ak_live_ if needed).',
       inputSchema: {
-        motorBlockId: z.string().uuid().optional().describe('Block used when minting a token if none cached')
+        motorBlockId: z.string().uuid().optional().describe('Optional. Listing is account-wide; a block is only used when minting a legacy public token on the non-OAuth path.')
       }
     },
     async (args) => {
@@ -90,7 +105,7 @@ export function createMotoricalMcpServer(options = {}) {
     }
   );
 
-  server.registerTool(
+  registerTool(
     'motorical_send_email',
     {
       description:
@@ -115,7 +130,12 @@ export function createMotoricalMcpServer(options = {}) {
           .boolean()
           .optional()
           .describe('Required true when dryRun is false'),
-        idempotencyKey: z.string().optional()
+        idempotencyKey: z.string().optional(),
+        motorBlockId: z
+          .string()
+          .uuid()
+          .optional()
+          .describe('Required when the authorization covers more than one Motor Block')
       }
     },
     async (args) => {
@@ -127,7 +147,7 @@ export function createMotoricalMcpServer(options = {}) {
     }
   );
 
-  server.registerTool(
+  registerTool(
     'motorical_get_message',
     {
       description: 'Get a message by send UUID (GET /api/public/v1/messages/{id}). Auto-mints bearer if needed.',
@@ -146,7 +166,7 @@ export function createMotoricalMcpServer(options = {}) {
     }
   );
 
-  server.registerTool(
+  registerTool(
     'motorical_get_message_events',
     {
       description:
@@ -166,7 +186,7 @@ export function createMotoricalMcpServer(options = {}) {
     }
   );
 
-  server.registerTool(
+  registerTool(
     'motorical_sandbox_status',
     {
       description:
@@ -186,7 +206,7 @@ export function createMotoricalMcpServer(options = {}) {
     }
   );
 
-  server.registerTool(
+  registerTool(
     'motorical_sandbox_allowlist_request',
     {
       description:
@@ -206,7 +226,7 @@ export function createMotoricalMcpServer(options = {}) {
     }
   );
 
-  server.registerTool(
+  registerTool(
     'motorical_sandbox_allowlist_confirm',
     {
       description:
@@ -227,7 +247,7 @@ export function createMotoricalMcpServer(options = {}) {
     }
   );
 
-  server.registerTool(
+  registerTool(
     'motorical_sandbox_provision',
     {
       description:
@@ -247,7 +267,7 @@ export function createMotoricalMcpServer(options = {}) {
     }
   );
 
-  server.registerTool(
+  registerTool(
     'motorical_sandbox_convert',
     {
       description:
@@ -267,7 +287,7 @@ export function createMotoricalMcpServer(options = {}) {
     }
   );
 
-  server.registerTool(
+  registerTool(
     'motorical_domain_add',
     {
       description:
@@ -277,7 +297,12 @@ export function createMotoricalMcpServer(options = {}) {
         'this account before asking the user to resolve the conflict. Requires MOTORICAL_JWT.',
       inputSchema: {
         domain: z.string().min(3),
-        verificationMethod: z.enum(['dns', 'email']).optional()
+        verificationMethod: z.enum(['dns', 'email']).optional(),
+        motorBlockId: z
+          .string()
+          .uuid()
+          .optional()
+          .describe('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.')
       }
     },
     async (args) => {
@@ -289,25 +314,31 @@ export function createMotoricalMcpServer(options = {}) {
     }
   );
 
-  server.registerTool(
+  registerTool(
     'motorical_domain_list',
     {
       description:
         'List domains already on this account (GET /api/domains) — 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). Requires MOTORICAL_JWT.',
-      inputSchema: {}
+      inputSchema: {
+        motorBlockId: z
+          .string()
+          .uuid()
+          .optional()
+          .describe('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.')
+      }
     },
-    async () => {
+    async (args) => {
       try {
-        return jsonResult(await client.domainList());
+        return jsonResult(await client.domainList(args));
       } catch (err) {
         return errorResult(err);
       }
     }
   );
 
-  server.registerTool(
+  registerTool(
     'motorical_domain_verify',
     {
       description:
@@ -315,7 +346,12 @@ export function createMotoricalMcpServer(options = {}) {
         'Safe to re-call after ownership is done — returns sendReady. Requires MOTORICAL_JWT.',
       inputSchema: {
         domainId: z.string().uuid(),
-        method: z.enum(['dns', 'email']).optional()
+        method: z.enum(['dns', 'email']).optional(),
+        motorBlockId: z
+          .string()
+          .uuid()
+          .optional()
+          .describe('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.')
       }
     },
     async (args) => {
@@ -327,7 +363,7 @@ export function createMotoricalMcpServer(options = {}) {
     }
   );
 
-  server.registerTool(
+  registerTool(
     'motorical_domain_check_dns',
     {
       description:
@@ -335,7 +371,12 @@ export function createMotoricalMcpServer(options = {}) {
         'Required before /v1/send when ownership is verified but send returns DOMAIN_DNS_INCOMPLETE. Requires MOTORICAL_JWT.',
       inputSchema: {
         domainId: z.string().uuid(),
-        recordType: z.enum(['dkim', 'spf', 'dmarc', 'mx']).optional()
+        recordType: z.enum(['dkim', 'spf', 'dmarc', 'mx']).optional(),
+        motorBlockId: z
+          .string()
+          .uuid()
+          .optional()
+          .describe('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.')
       }
     },
     async (args) => {
@@ -347,7 +388,7 @@ export function createMotoricalMcpServer(options = {}) {
     }
   );
 
-  server.registerTool(
+  registerTool(
     'motorical_web_handoff',
     {
       description:
@@ -366,6 +407,155 @@ export function createMotoricalMcpServer(options = {}) {
     }
   );
 
+  // ---- Analytics & health tools ----
+  // Each wraps one existing Public API route one-to-one. See
+  // motorical-docs/plans/2026-09-02-mcp-analytics-health-tools-implementation.md.
+  // .optional() on purpose, matching every pre-existing block-scoped tool: a
+  // grant covering exactly one Motor Block resolves it automatically, so the
+  // caller only has to name one when the grant covers several. Making it
+  // required forces single-block users to supply an id they should never need,
+  // and turns the multi-block case into a Zod type error instead of
+  // resolveBlock's actionable message.
+  const blockSelector = z.string().uuid().optional()
+    .describe('Required when the authorization covers more than one Motor Block');
+  const isoDate = (bound) => z.string().optional().describe(`ISO date or datetime, ${bound}`);
+
+  registerTool(
+    'motorical_get_overview',
+    {
+      description:
+        'Sending overview for one Motor Block over a date range — volume, delivery and bounce '
+        + 'rates, and current usage against plan limits (GET /api/public/v1/motor-blocks/{id}/overview).',
+      inputSchema: {
+        motorBlockId: blockSelector,
+        from: isoDate('inclusive'),
+        to: isoDate('inclusive')
+      }
+    },
+    async (args) => {
+      try {
+        return jsonResult(await client.getOverview(args));
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  );
+
+  registerTool('motorical_get_daily_summary', {
+    description: 'Per-day send counts and outcomes for one Motor Block (GET /api/public/v1/motor-blocks/{id}/daily-summary).',
+    inputSchema: {
+      motorBlockId: blockSelector,
+      days: z.number().int().positive().optional().describe('How many days back, counting today')
+    }
+  }, async (args) => { try { return jsonResult(await client.getDailySummary(args)); } catch (err) { return errorResult(err); } });
+
+  registerTool('motorical_get_metrics', {
+    description: 'Time-series send metrics for one Motor Block, bucketed by hour or day (GET /api/public/v1/motor-blocks/{id}/metrics).',
+    inputSchema: {
+      motorBlockId: blockSelector,
+      from: isoDate('inclusive'),
+      to: isoDate('inclusive'),
+      interval: z.enum(['hour', 'day']).optional().describe('Bucket size; defaults to the API default')
+    }
+  }, async (args) => { try { return jsonResult(await client.getMetrics(args)); } catch (err) { return errorResult(err); } });
+
+  registerTool('motorical_get_deliverability', {
+    description: 'Deliverability broken down by recipient domain (GET /api/public/v1/motor-blocks/{id}/deliverability).',
+    inputSchema: {
+      motorBlockId: blockSelector,
+      from: isoDate('inclusive'),
+      to: isoDate('inclusive'),
+      limit: z.number().int().positive().optional().describe('Max recipient domains returned')
+    }
+  }, async (args) => { try { return jsonResult(await client.getDeliverability(args)); } catch (err) { return errorResult(err); } });
+
+  registerTool('motorical_get_reputation', {
+    description: 'Current sending reputation for one Motor Block (GET /api/public/v1/motor-blocks/{id}/reputation).',
+    inputSchema: { motorBlockId: blockSelector }
+  }, async (args) => { try { return jsonResult(await client.getReputation(args)); } catch (err) { return errorResult(err); } });
+
+  registerTool('motorical_get_anomalies', {
+    description: 'Detected sending anomalies for one Motor Block — volume spikes, bounce surges, unusual patterns (GET /api/public/v1/motor-blocks/{id}/anomalies).',
+    inputSchema: { motorBlockId: blockSelector }
+  }, async (args) => { try { return jsonResult(await client.getAnomalies(args)); } catch (err) { return errorResult(err); } });
+
+  registerTool('motorical_get_providers', {
+    description: 'Send outcomes grouped by receiving mailbox provider (GET /api/public/v1/motor-blocks/{id}/providers).',
+    inputSchema: {
+      motorBlockId: blockSelector,
+      from: isoDate('inclusive'),
+      to: isoDate('inclusive'),
+      limit: z.number().int().positive().optional().describe('Max providers returned')
+    }
+  }, async (args) => { try { return jsonResult(await client.getProviders(args)); } catch (err) { return errorResult(err); } });
+
+  registerTool('motorical_get_error_codes', {
+    description: 'SMTP error codes seen for one Motor Block, with counts and diagnostics (GET /api/public/v1/motor-blocks/{id}/error-codes).',
+    inputSchema: {
+      motorBlockId: blockSelector,
+      from: isoDate('inclusive'),
+      to: isoDate('inclusive'),
+      limit: z.number().int().positive().optional().describe('Max distinct error codes returned')
+    }
+  }, async (args) => { try { return jsonResult(await client.getErrorCodes(args)); } catch (err) { return errorResult(err); } });
+
+  registerTool('motorical_get_rate_limits', {
+    description: "Current hourly and daily send usage against this Motor Block's limits (GET /api/public/v1/motor-blocks/{id}/rate-limits).",
+    inputSchema: { motorBlockId: blockSelector }
+  }, async (args) => { try { return jsonResult(await client.getRateLimits(args)); } catch (err) { return errorResult(err); } });
+
+  registerTool('motorical_get_account_rate_limits', {
+    description:
+      'Account-wide send ceiling and current usage across every Motor Block '
+      + '(GET /api/public/v1/account/rate-limits). Account-scoped: no Motor Block needed.',
+    inputSchema: {
+      motorBlockId: z.string().uuid().optional()
+        .describe('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.')
+    }
+  }, async (args) => { try { return jsonResult(await client.getAccountRateLimits(args)); } catch (err) { return errorResult(err); } });
+
+  registerTool('motorical_get_logs', {
+    description:
+      'Search send logs for one Motor Block (GET /api/public/v1/motor-blocks/{id}/logs). '
+      + 'Paginate with cursor. Recipient addresses are masked unless the token carries logs.pii, '
+      + 'which OAuth tokens never do.',
+    inputSchema: {
+      motorBlockId: blockSelector,
+      from: isoDate('inclusive'),
+      to: isoDate('inclusive'),
+      currentOutcome: z.string().optional().describe('Filter to one delivery outcome, e.g. delivered, bounced, deferred'),
+      query: z.string().optional().describe('Free-text match against recipient, subject or message id'),
+      limit: z.number().int().positive().optional().describe('Page size'),
+      cursor: z.string().optional().describe('Opaque cursor from a previous page'),
+      includePII: z.boolean().optional().describe('Unmask recipient addresses. Requires the logs.pii scope, which is never granted to OAuth tokens — the API returns 403.')
+    }
+  }, async (args) => { try { return jsonResult(await client.getLogs(args)); } catch (err) { return errorResult(err); } });
+
+  registerTool('motorical_get_message_by_smtp_id', {
+    description:
+      'Look up one message by its SMTP Message-ID header (GET /api/public/v1/messages?smtpMessageId=). '
+      + 'This is a lookup, not a listing: an exact id is required and at most one message is returned. '
+      + 'Use motorical_get_message when you have the internal send UUID instead.',
+    inputSchema: {
+      smtpMessageId: z.string().describe('The exact SMTP Message-ID, angle brackets included'),
+      motorBlockId: blockSelector,
+      includePII: z.boolean().optional().describe('Unmask the recipient address. Requires the logs.pii scope, which is never granted to OAuth tokens — the API returns 403.')
+    }
+  }, async (args) => { try { return jsonResult(await client.getMessageBySmtpId(args)); } catch (err) { return errorResult(err); } });
+
+  registerTool('motorical_get_config', {
+    description: "Configuration of one Motor Block — its sending domain, limits and delivery settings (GET /api/public/v1/motor-blocks/{id}/config).",
+    inputSchema: { motorBlockId: blockSelector }
+  }, async (args) => { try { return jsonResult(await client.getConfig(args)); } catch (err) { return errorResult(err); } });
+
+  registerTool('motorical_get_domain_health', {
+    description: "DNS and email-authentication health for the Motor Block's sending domain — SPF, DKIM, DMARC, MX (GET /api/public/v1/motor-blocks/{id}/domain-health).",
+    inputSchema: {
+      motorBlockId: blockSelector,
+      refresh: z.boolean().optional().describe('Re-run the live DNS checks now instead of returning the last cached result')
+    }
+  }, async (args) => { try { return jsonResult(await client.getDomainHealth(args)); } catch (err) { return errorResult(err); } });
+
   server.registerResource(
     'motorical-llms',
     'motorical://docs/llms.txt',