@motorical/mcp 1.1.3 → 1.2.1

package/README.md

@@ -25,6 +25,39 @@ A **Motorical SMTP Motor Block** is an isolated sending stream (similar to a per
 
 Safety: real sends require `dryRun: false` **and** `confirmRealSend: true`. Sandbox outbound is allowlist-locked until convert. Optional `fromName` sets the inbox display name (same as HTTP `/v1/send` / CLI `--from-name`); do not put `From` in custom headers.
 
+## Authorization (recommended)
+
+Sign in once; no keys to paste, copy, or rotate by hand:
+
+```bash
+npx @motorical/mcp login
+```
+
+This opens your browser, you approve the scopes on Motorical's consent screen,
+and the grant is stored at `~/.motorical/mcp-credentials.json` (owner-only,
+`0600`). Access tokens last an hour and refresh silently.
+
+- `motorical-mcp status` — show the current connection
+
+An authorization covers **every Motor Block you own**, so block-scoped calls
+must say which one they mean. Set `MOTORICAL_MOTOR_BLOCK_ID` (or pass
+`motorBlockId` per call); the tools fail with a clear message rather than a bare
+API error if it is missing.
+- `motorical-mcp logout` — remove the local credentials
+
+Logging out only deletes the local file. To cut the agent's access off at the
+server, revoke the connection in **Settings → API Access → Connected AI
+Agents**; that takes effect immediately, on every device, and does not sign you
+out of your own dashboard.
+
+Under the hood this is OAuth 2.1: PKCE `S256`, a loopback redirect, RFC 8707
+audience-bound tokens, and RFC 9207 issuer checking on the callback. The client
+is public, so refresh tokens rotate on every use.
+
+The environment variables below still work and are the right choice for CI or a
+headless server, where no browser is available. When an OAuth session is present
+it takes precedence over them.
+
 ## Environment
 
 | Variable | Required | Description |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motorical/mcp",
-  "version": "1.1.3",
+  "version": "1.2.1",
   "description": "MCP server for Motorical transactional email API — dry-run/send, mint public tokens, list Motor Blocks, inspect delivery events",
   "type": "module",
   "bin": {
@@ -42,7 +42,7 @@
   },
   "homepage": "https://docs.motorical.com/ai-mcp",
   "bugs": {
-    "url": "https://github.com/motorical-smtp/motorical-packages/issues"
+    "url": "https://github.com/motorical-smtp/motorical-backend/issues"
   },
   "repository": {
     "type": "git",

package/src/client.js

@@ -3,9 +3,26 @@
  * 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';
+
 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(/\/$/, ''),
@@ -15,7 +32,9 @@ export function loadConfig(env = process.env) {
     bearerToken: env.MOTORICAL_BEARER_TOKEN || '',
     dashboardJwt: env.MOTORICAL_JWT || '',
     motorBlockId: env.MOTORICAL_MOTOR_BLOCK_ID || '',
-    defaultFrom: env.MOTORICAL_DEFAULT_FROM || ''
+    defaultFrom: env.MOTORICAL_DEFAULT_FROM || '',
+    // A grant from `motorical-mcp login`, when one exists.
+    oauthCredentials: loadCredentials()
   };
 }
 
@@ -26,19 +45,76 @@ export class MotoricalClient {
     this._cachedBearer = config.bearerToken || null;
     /** @type {string|null} */
     this._cachedMkKey = null;
+    /**
+     * An OAuth grant from `motorical-mcp login`. When present it is preferred
+     * over pasted keys: it is scoped, revocable from the dashboard, and expires.
+     */
+    // Read ONLY from config. An implicit loadCredentials() here would make the
+    // client behave differently on a machine that happens to have logged in —
+    // including inside tests. loadConfig() is the one place the disk is read.
+    this._oauth = config.oauthCredentials || null;
+    this._oauthMeta = null;
+  }
+
+  hasOAuthSession() {
+    return !!(this._oauth && this._oauth.accessToken);
+  }
+
+  /** Returns a live OAuth access token, refreshing (and rotating) if needed. */
+  async oauthAccessToken({ fetchImpl } = {}) {
+    if (!this.hasOAuthSession()) return null;
+    if (!isExpired(this._oauth)) return this._oauth.accessToken;
+
+    if (!this._oauth.refreshToken) {
+      throw new Error('Motorical session expired and has no refresh token. Run: motorical-mcp login');
+    }
+    if (!this._oauthMeta) {
+      this._oauthMeta = await discover(this._oauth.issuer, fetchImpl || fetch);
+    }
+    let tokens;
+    try {
+      tokens = await refreshTokens(this._oauthMeta, { refreshToken: this._oauth.refreshToken }, fetchImpl || fetch);
+    } catch (err) {
+      throw new Error(`Motorical session could not be refreshed (${err.message}). Run: motorical-mcp login`);
+    }
+    this._oauth = {
+      ...this._oauth,
+      accessToken: tokens.access_token,
+      // Rotation is mandatory for public clients: the old refresh token is dead.
+      refreshToken: tokens.refresh_token || this._oauth.refreshToken,
+      scope: tokens.scope || this._oauth.scope,
+      expiresAt: Date.now() + (Number(tokens.expires_in || 3600) * 1000),
+    };
+    try { saveCredentials(this._oauth); } catch { /* keep working in-memory */ }
+    return this._oauth.accessToken;
   }
 
   requireMk() {
     if (this._cachedMkKey) return this._cachedMkKey;
     if (!this.config.mkApiKey) {
-      throw new Error('MOTORICAL_MK_API_KEY is required (mk_live_... Motor Block API key for POST /v1/send)');
+      throw new Error(
+        'No credentials for sending. Run `motorical-mcp login`, or set MOTORICAL_MK_API_KEY (mk_live_...).'
+      );
     }
     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';
@@ -96,7 +172,48 @@ export class MotoricalClient {
     return data;
   }
 
+  /**
+   * An OAuth grant covers every Motor Block the user owned at consent time, so
+   * a block-scoped request must say which one it means. (A minted public token
+   * carried a single block inside the token, so this never came up before.)
+   * Fails here with an actionable message rather than letting the API answer
+   * with a bare 400.
+   */
+  _scoped(path, motorBlockId) {
+    if (!this.hasOAuthSession()) return path;
+    const id = motorBlockId || this.config.motorBlockId;
+    if (!id) {
+      throw new Error(
+        'motorBlockId is required: your Motorical authorization covers multiple Motor Blocks. '
+        + 'Pass motorBlockId, or set MOTORICAL_MOTOR_BLOCK_ID.'
+      );
+    }
+    const sep = path.includes('?') ? '&' : '?';
+    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)}`;
+  }
+
   async getBearer({ motorBlockId, forceRefresh = false } = {}) {
+    // An OAuth grant supersedes minted public tokens entirely — no ak_live_ key
+    // and no dashboard JWT needed.
+    const oauthToken = await this.oauthAccessToken();
+    if (oauthToken) return oauthToken;
+
     if (this._cachedBearer && !forceRefresh) return this._cachedBearer;
     const minted = await this.mintPublicToken({ motorBlockId });
     const token = minted?.data?.token || minted?.token || minted?.access_token;
@@ -107,7 +224,7 @@ export class MotoricalClient {
 
   async listMotorBlocks({ motorBlockId } = {}) {
     const bearer = await this.getBearer({ motorBlockId });
-    return this.request('GET', '/api/public/v1/motor-blocks', { bearer });
+    return this.request('GET', this._accountPath('/api/public/v1/motor-blocks', motorBlockId), { bearer });
   }
 
   async sendEmail(payload) {
@@ -122,6 +239,7 @@ export class MotoricalClient {
       confirmRealSend = false,
       idempotencyKey,
       headers: customHeaders,
+      motorBlockId: _motorBlockId, // never in the body — see sendPath below
       ...rest
     } = payload;
 
@@ -140,8 +258,25 @@ export class MotoricalClient {
     const headers = {};
     if (idempotencyKey) headers['Idempotency-Key'] = idempotencyKey;
 
-    return this.request('POST', '/v1/send', {
-      apiKey: this.requireMk(),
+    const oauthToken = await this.oauthAccessToken();
+    if (oauthToken && !this.config.motorBlockId && !payload.motorBlockId) {
+      throw new Error(
+        'motorBlockId is required to send with an OAuth authorization: it covers every Motor Block '
+        + 'you own. Set MOTORICAL_MOTOR_BLOCK_ID, or pass motorBlockId.'
+      );
+    }
+    const auth = oauthToken ? { bearer: oauthToken } : { apiKey: this.requireMk() };
+
+    // The block goes in the query string, not the body: /v1/send validates its
+    // body strictly and rejects unknown keys, and an api-key client's block
+    // comes from the key itself — a body field that disagreed would be a
+    // silent footgun.
+    const sendPath = oauthToken
+      ? `/v1/send?motorBlockId=${encodeURIComponent(payload.motorBlockId || this.config.motorBlockId)}`
+      : '/v1/send';
+
+    return this.request('POST', sendPath, {
+      ...auth,
       headers,
       body: {
         from: fromAddr,
@@ -161,14 +296,14 @@ export class MotoricalClient {
     if (!messageId) throw new Error('messageId is required');
     const bearer = await this.getBearer({ motorBlockId });
     const q = includePII ? '?includePII=true' : '';
-    return this.request('GET', `/api/public/v1/messages/${encodeURIComponent(messageId)}${q}`, { bearer });
+    return this.request('GET', this._scoped(`/api/public/v1/messages/${encodeURIComponent(messageId)}${q}`, motorBlockId), { bearer });
   }
 
   async getMessageEvents(messageId, { includePII = false, motorBlockId } = {}) {
     if (!messageId) throw new Error('messageId is required');
     const bearer = await this.getBearer({ motorBlockId });
     const q = includePII ? '?includePII=true' : '';
-    return this.request('GET', `/api/public/v1/messages/${encodeURIComponent(messageId)}/events${q}`, { bearer });
+    return this.request('GET', this._scoped(`/api/public/v1/messages/${encodeURIComponent(messageId)}/events${q}`, motorBlockId), { bearer });
   }
 
   async getSendApiStatus() {
@@ -218,34 +353,85 @@ export class MotoricalClient {
     });
   }
 
-  async domainList() {
-    return this.request('GET', '/api/domains', {
-      bearer: this.requireDashboardJwt()
-    });
+  // 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() });
+    }
+    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/index.js

@@ -1,13 +1,38 @@
 #!/usr/bin/env node
 /**
  * Motorical MCP server — stdio transport for Cursor / Claude Desktop / etc.
- * Credentials via env (see README). Log only to stderr.
+ * Auth: `motorical-mcp login` (OAuth 2.1), or env credentials (see README).
+ * Log only to stderr — stdout is the MCP stream.
  */
 
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { createMotoricalMcpServer } from './server.js';
 
+const USAGE = `motorical-mcp — Motorical MCP server
+
+  motorical-mcp             start the MCP server on stdio (default)
+  motorical-mcp login       authorize with Motorical in your browser
+  motorical-mcp logout      revoke the authorization and remove local credentials
+                            (--local-only to forget it without revoking)
+  motorical-mcp status      show the current connection
+`;
+
 async function main() {
+  const cmd = process.argv[2];
+
+  if (cmd === 'login' || cmd === 'logout' || cmd === 'status') {
+    const mod = await import('./login.js');
+    if (cmd === 'login') await mod.login();
+    if (cmd === 'logout') await mod.logout({ revoke: !process.argv.includes('--local-only') });
+    if (cmd === 'status') mod.status();
+    return;
+  }
+
+  if (cmd === '--help' || cmd === '-h' || cmd === 'help') {
+    console.error(USAGE);
+    return;
+  }
+
   const { server } = createMotoricalMcpServer();
   const transport = new StdioServerTransport();
   await server.connect(transport);
@@ -15,6 +40,6 @@ async function main() {
 }
 
 main().catch((err) => {
-  console.error('[motorical-mcp] fatal:', err);
+  console.error('[motorical-mcp] fatal:', err.message || err);
   process.exit(1);
 });

package/src/login.js

@@ -0,0 +1,105 @@
+/**
+ * `motorical-mcp login` — interactive OAuth 2.1 authorization.
+ * Everything it prints goes to stderr so it never corrupts an stdio MCP stream.
+ */
+
+import crypto from 'node:crypto';
+import { spawn } from 'node:child_process';
+import {
+  DEFAULT_ISSUER, DEFAULT_RESOURCE,
+  discover, generatePkce, buildAuthorizeUrl, startCallbackServer,
+  exchangeCode, toStoredCredentials, saveCredentials, clearCredentials, revokeToken,
+  credentialsPath, loadCredentials,
+} from './oauth.js';
+
+const DEFAULT_SCOPES = ['send:transactional', 'read:analytics', 'manage:domains'];
+
+function openBrowser(url) {
+  const cmd = process.platform === 'darwin' ? 'open'
+    : process.platform === 'win32' ? 'start' : 'xdg-open';
+  try {
+    spawn(cmd, [url], { stdio: 'ignore', detached: true, shell: process.platform === 'win32' }).unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function login({
+  issuer = process.env.MOTORICAL_ISSUER || DEFAULT_ISSUER,
+  resource = process.env.MOTORICAL_RESOURCE || DEFAULT_RESOURCE,
+  scopes = DEFAULT_SCOPES,
+  open = true,
+  log = (m) => console.error(m),
+} = {}) {
+  const meta = await discover(issuer);
+  const { verifier, challenge } = generatePkce();
+  const state = crypto.randomBytes(16).toString('base64url');
+
+  const server = await startCallbackServer({ expectedState: state, expectedIssuer: issuer });
+  const authorizeUrl = buildAuthorizeUrl(meta, {
+    redirectUri: server.redirectUri, challenge, state, scopes, resource,
+  });
+
+  log('');
+  log('Authorize Motorical in your browser:');
+  log(`  ${authorizeUrl}`);
+  log('');
+  if (open && !openBrowser(authorizeUrl)) {
+    log('(could not open a browser automatically — copy the link above)');
+  }
+
+  let code;
+  try {
+    code = await server.waitForCode;
+  } catch (err) {
+    server.close();
+    throw err;
+  }
+
+  const tokens = await exchangeCode(meta, {
+    code, verifier, redirectUri: server.redirectUri, resource,
+  });
+  const creds = toStoredCredentials(tokens, { issuer, resource });
+  const file = saveCredentials(creds);
+
+  log(`Connected. Credentials stored at ${file} (owner-only).`);
+  log(`Scopes granted: ${creds.scope || scopes.join(' ')}`);
+  return creds;
+}
+
+export async function logout({ log = (m) => console.error(m), revoke = true } = {}) {
+  const creds = loadCredentials();
+  if (!creds) { log('No stored credentials to remove.'); return false; }
+
+  if (revoke) {
+    try {
+      const meta = await discover(creds.issuer);
+      const ok = await revokeToken(meta, {
+        token: creds.refreshToken || creds.accessToken,
+        tokenTypeHint: creds.refreshToken ? 'refresh_token' : 'access_token',
+      });
+      log(ok
+        ? 'Revoked the authorization on the server.'
+        : 'Could not revoke on the server — revoke it in Settings → API Access.');
+    } catch (err) {
+      log(`Could not reach the server to revoke (${err.message}).`);
+      log('The grant is still live — revoke it in Settings → API Access.');
+    }
+  }
+
+  const removed = clearCredentials();
+  log(removed ? `Removed ${credentialsPath()}.` : 'No local credentials file to remove.');
+  return removed;
+}
+
+export function status({ log = (m) => console.error(m) } = {}) {
+  const creds = loadCredentials();
+  if (!creds) { log('Not connected. Run: motorical-mcp login'); return null; }
+  log(`Connected to ${creds.issuer}`);
+  log(`  resource: ${creds.resource}`);
+  log(`  scopes:   ${creds.scope || '(unknown)'}`);
+  log(`  expires:  ${new Date(creds.expiresAt).toISOString()}`);
+  log(`  file:     ${credentialsPath()}`);
+  return creds;
+}

package/src/oauth.js

@@ -0,0 +1,235 @@
+/**
+ * OAuth 2.1 + PKCE login for the Motorical MCP server.
+ *
+ * Replaces pasted mk_live_/ak_live_ keys: the user authorizes once in a
+ * browser and the resulting grant is stored locally and refreshed silently.
+ * The client is public (no secret), so PKCE S256 and refresh rotation are
+ * mandatory rather than optional.
+ */
+
+import http from 'node:http';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+export const DEFAULT_ISSUER = 'https://motorical.com';
+export const DEFAULT_RESOURCE = 'https://api.motorical.com';
+export const CLIENT_ID = 'https://motorical.com/.well-known/motorical-mcp-client.json';
+
+const CREDENTIALS_DIR = path.join(os.homedir(), '.motorical');
+const CREDENTIALS_FILE = path.join(CREDENTIALS_DIR, 'mcp-credentials.json');
+
+/** Tokens are user credentials: owner-only, never world-readable. */
+export function saveCredentials(creds, file = CREDENTIALS_FILE) {
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(file, JSON.stringify(creds, null, 2), { mode: 0o600 });
+  try { fs.chmodSync(file, 0o600); } catch { /* best effort on odd filesystems */ }
+  return file;
+}
+
+export function loadCredentials(file = CREDENTIALS_FILE) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function clearCredentials(file = CREDENTIALS_FILE) {
+  try { fs.unlinkSync(file); return true; } catch { return false; }
+}
+
+export function credentialsPath() { return CREDENTIALS_FILE; }
+
+export function generatePkce() {
+  const verifier = crypto.randomBytes(32).toString('base64url');
+  const challenge = crypto.createHash('sha256').update(verifier).digest('base64url');
+  return { verifier, challenge };
+}
+
+/** RFC 8414 discovery, so endpoints are never hardcoded past the issuer. */
+export async function discover(issuer = DEFAULT_ISSUER, fetchImpl = fetch) {
+  const res = await fetchImpl(`${issuer}/.well-known/oauth-authorization-server`, {
+    headers: { Accept: 'application/json' },
+  });
+  if (!res.ok) throw new Error(`Discovery failed: HTTP ${res.status}`);
+  const meta = await res.json();
+  if (meta.issuer !== issuer) {
+    throw new Error(`Issuer mismatch: document says ${meta.issuer}, expected ${issuer}`);
+  }
+  // A client MUST refuse to continue without PKCE S256 support.
+  if (!Array.isArray(meta.code_challenge_methods_supported)
+      || !meta.code_challenge_methods_supported.includes('S256')) {
+    throw new Error('Authorization server does not advertise PKCE S256 — refusing to continue');
+  }
+  return meta;
+}
+
+export function buildAuthorizeUrl(meta, { redirectUri, challenge, state, scopes, resource }) {
+  const u = new URL(meta.authorization_endpoint);
+  u.searchParams.set('client_id', CLIENT_ID);
+  u.searchParams.set('response_type', 'code');
+  u.searchParams.set('redirect_uri', redirectUri);
+  u.searchParams.set('scope', scopes.join(' '));
+  u.searchParams.set('state', state);
+  u.searchParams.set('code_challenge', challenge);
+  u.searchParams.set('code_challenge_method', 'S256');
+  u.searchParams.set('resource', resource);
+  return u.toString();
+}
+
+/**
+ * RFC 9207: the callback carries `iss`. Comparing it to the issuer we
+ * discovered is what stops a mix-up attack, where a malicious AS relays the
+ * user to a different one and harvests the code.
+ */
+export function validateCallback({ params, expectedState, expectedIssuer }) {
+  if (params.get('error')) {
+    throw new Error(params.get('error_description') || params.get('error'));
+  }
+  if (params.get('state') !== expectedState) {
+    throw new Error('State mismatch — discarding this callback');
+  }
+  const iss = params.get('iss');
+  if (iss && iss !== expectedIssuer) {
+    throw new Error(`Issuer mismatch in callback: ${iss}`);
+  }
+  const code = params.get('code');
+  if (!code) throw new Error('Authorization callback carried no code');
+  return code;
+}
+
+export async function exchangeCode(meta, { code, verifier, redirectUri, resource }, fetchImpl = fetch) {
+  const body = new URLSearchParams({
+    grant_type: 'authorization_code',
+    code,
+    client_id: CLIENT_ID,
+    redirect_uri: redirectUri,
+    code_verifier: verifier,
+    resource,
+  });
+  const res = await fetchImpl(meta.token_endpoint, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
+    body: body.toString(),
+  });
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) throw new Error(data.error_description || data.error || `Token exchange failed: HTTP ${res.status}`);
+  return data;
+}
+
+export async function refreshTokens(meta, { refreshToken }, fetchImpl = fetch) {
+  const body = new URLSearchParams({
+    grant_type: 'refresh_token',
+    refresh_token: refreshToken,
+    client_id: CLIENT_ID,
+  });
+  const res = await fetchImpl(meta.token_endpoint, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
+    body: body.toString(),
+  });
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) throw new Error(data.error_description || data.error || `Refresh failed: HTTP ${res.status}`);
+  return data;
+}
+
+/**
+ * RFC 7009. Deleting the local file leaves the grant alive on the server —
+ * still valid, still refreshable, belonging to nobody. "Log out" should mean
+ * the access is gone, so revoke before forgetting.
+ */
+export async function revokeToken(meta, { token, tokenTypeHint = 'refresh_token' }, fetchImpl = fetch) {
+  if (!meta?.revocation_endpoint) return false;
+  const body = new URLSearchParams({
+    token, token_type_hint: tokenTypeHint, client_id: CLIENT_ID,
+  });
+  const res = await fetchImpl(meta.revocation_endpoint, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: body.toString(),
+  });
+  return res.ok;
+}
+
+/** Shape stored on disk; `expiresAt` is absolute so a stale clock is obvious. */
+export function toStoredCredentials(tokenResponse, { issuer, resource }) {
+  return {
+    version: 1,
+    issuer,
+    resource,
+    accessToken: tokenResponse.access_token,
+    refreshToken: tokenResponse.refresh_token || null,
+    scope: tokenResponse.scope || '',
+    expiresAt: Date.now() + (Number(tokenResponse.expires_in || 3600) * 1000),
+    obtainedAt: Date.now(),
+  };
+}
+
+/** 60s skew so a token is never used in the instant before it expires. */
+export function isExpired(creds, now = Date.now()) {
+  if (!creds?.expiresAt) return true;
+  return now >= (creds.expiresAt - 60_000);
+}
+
+/**
+ * Starts the loopback listener and returns the chosen port immediately, since
+ * the port has to go into the authorize URL before any code can arrive.
+ */
+export function startCallbackServer({ expectedState, expectedIssuer, timeoutMs = 300_000 }) {
+  return new Promise((resolveStart, rejectStart) => {
+    let settle;
+    const waitForCode = new Promise((resolve, reject) => { settle = { resolve, reject }; });
+
+    const server = http.createServer((req, res) => {
+      const url = new URL(req.url, 'http://127.0.0.1');
+      if (url.pathname !== '/callback') { res.writeHead(404).end('Not found'); return; }
+      try {
+        const code = validateCallback({ params: url.searchParams, expectedState, expectedIssuer });
+        res.writeHead(200, { 'Content-Type': 'text/html' }).end(page(
+          'Motorical is connected',
+          'You can close this tab and return to your terminal.'
+        ));
+        finish(); settle.resolve(code);
+      } catch (err) {
+        res.writeHead(400, { 'Content-Type': 'text/html' }).end(page(
+          'Authorization failed', escapeHtml(err.message)
+        ));
+        finish(); settle.reject(err);
+      }
+    });
+
+    const timer = setTimeout(() => {
+      finish();
+      settle.reject(new Error('Timed out waiting for the browser callback'));
+    }, timeoutMs);
+
+    function finish() {
+      clearTimeout(timer);
+      setImmediate(() => server.close(() => {}));
+    }
+
+    server.on('error', (err) => { clearTimeout(timer); rejectStart(err); });
+    // Port 0 = whatever the OS gives us; the AS matches loopback ignoring port.
+    server.listen(0, '127.0.0.1', () => {
+      const { port } = server.address();
+      resolveStart({
+        port,
+        redirectUri: `http://127.0.0.1:${port}/callback`,
+        waitForCode,
+        close: finish,
+      });
+    });
+  });
+}
+
+function page(title, body) {
+  return `<html><body style="font-family:system-ui;padding:3rem;text-align:center"><h2>${title}</h2><p>${body}</p></body></html>`;
+}
+
+function escapeHtml(s) {
+  return String(s).replace(/[&<>"']/g, (c) => (
+    { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]
+  ));
+}

package/src/server.js

@@ -34,7 +34,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 +62,7 @@ export function createMotoricalMcpServer(options = {}) {
     }
   );
 
-  server.registerTool(
+  registerTool(
     'motorical_mint_public_token',
     {
       description:
@@ -72,13 +84,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 +102,7 @@ export function createMotoricalMcpServer(options = {}) {
     }
   );
 
-  server.registerTool(
+  registerTool(
     'motorical_send_email',
     {
       description:
@@ -115,7 +127,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 +144,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 +163,7 @@ export function createMotoricalMcpServer(options = {}) {
     }
   );
 
-  server.registerTool(
+  registerTool(
     'motorical_get_message_events',
     {
       description:
@@ -166,7 +183,7 @@ export function createMotoricalMcpServer(options = {}) {
     }
   );
 
-  server.registerTool(
+  registerTool(
     'motorical_sandbox_status',
     {
       description:
@@ -186,7 +203,7 @@ export function createMotoricalMcpServer(options = {}) {
     }
   );
 
-  server.registerTool(
+  registerTool(
     'motorical_sandbox_allowlist_request',
     {
       description:
@@ -206,7 +223,7 @@ export function createMotoricalMcpServer(options = {}) {
     }
   );
 
-  server.registerTool(
+  registerTool(
     'motorical_sandbox_allowlist_confirm',
     {
       description:
@@ -227,7 +244,7 @@ export function createMotoricalMcpServer(options = {}) {
     }
   );
 
-  server.registerTool(
+  registerTool(
     'motorical_sandbox_provision',
     {
       description:
@@ -247,7 +264,7 @@ export function createMotoricalMcpServer(options = {}) {
     }
   );
 
-  server.registerTool(
+  registerTool(
     'motorical_sandbox_convert',
     {
       description:
@@ -267,7 +284,7 @@ export function createMotoricalMcpServer(options = {}) {
     }
   );
 
-  server.registerTool(
+  registerTool(
     'motorical_domain_add',
     {
       description:
@@ -277,7 +294,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 +311,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 +343,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 +360,7 @@ export function createMotoricalMcpServer(options = {}) {
     }
   );
 
-  server.registerTool(
+  registerTool(
     'motorical_domain_check_dns',
     {
       description:
@@ -335,7 +368,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 +385,7 @@ export function createMotoricalMcpServer(options = {}) {
     }
   );
 
-  server.registerTool(
+  registerTool(
     'motorical_web_handoff',
     {
       description: