Motorical MCP
There are two separate ways to give an AI agent MCP access to Motorical. They share the same underlying tool implementations, but they're different running things, authenticated differently, and deployed independently — a fix to one does not reach the other until it's separately released.
| Local server (npm package) | Hosted server (OAuth) | |
|---|---|---|
| What it is | A process you run yourself (npx, npm install -g, or a Cursor/Claude Desktop config) | An always-on service at mcp.motorical.com |
| Transport | stdio | Streamable HTTP |
| Auth | mk_live_/ak_live_ keys, dashboard JWT, or a locally-stored OAuth session | OAuth 2.1 + PKCE — no keys to manage, browser consent on first use; or none at all, for the signup handoff below |
| Install | Yes — npm install -g or npx | No — just point a compatible client at a URL |
| Tool catalogue | Every tool, including sandbox provisioning and browser handoff (listed on the local page) | 50 tools across 8 scoped servers, including production Motor Block lifecycle management (create, rename, type, domain, deactivate, delete); only allowlisting by 6-digit code and the web-handoff tool are unavailable over OAuth (recipients confirm by emailed link through motorical_free_recipient_add instead) — sandbox status/provision/convert work over OAuth like any other account-scoped tool |
| Sandbox credentials | motorical_sandbox_provision returns the mk_live_ key directly, once | Never returned inline — credentialsAvailable:false on provision, a credentialsLocation dashboard link after motorical_sandbox_convert, which also lets you choose the production name/type and replaces the SMTP username |
Which route
Which one do I use? There are three routes, and you need only one.
- Hosted MCP (the default, nothing to install). You connect Motorical to your assistant with the steps below and create your account in the browser. The assistant never holds a password or key. Choose this when you are in Claude Code, Claude Desktop or Claude.ai and a person is at the keyboard.
- Agent-led onboarding (no connector needed). The assistant does the sign-up itself over the HTTP API: you give it your email address and read it the 6-digit code that arrives by email, and it provisions your sandbox and sends a first message. When you want the dashboard, it hands you a one-time link (valid for 90 seconds) to open in your browser, where you set your own password. Choose this when the assistant can run shell or HTTP requests and you would rather not add a connector. The assistant briefly holds a session token, which the hosted route avoids.
- Local npm package
@motorical/mcp. A program you run on your own machine over stdio, signed in with an API key or a stored login. Choose it only if your client cannot use remote MCP servers, or you need allowlisting by 6-digit code, the browser-handoff tool, or unmasked recipient addresses. Neither route above needs it.@motorical/cliis retired.
Connect
Connect (hosted, nothing to install). In your terminal, in a normal shell and not inside a Claude session, run claude mcp add --transport http motorical https://mcp.motorical.com/v1/motorical/mcp. Then start a new Claude Code session (one that was already open may not list the new server), type /mcp, pick motorical, and choose Authenticate. If you would rather have an account first, create it at https://motorical.com/register and then connect; sign-in at the consent step works the same. A browser opens: sign in, or create your account (two-factor authentication is required and cannot be skipped), then press Allow. Back in the session the Motorical tools are there; you do not run Authenticate a second time. In Claude Desktop or Claude.ai, add a custom connector with the same URL (https://mcp.motorical.com/v1/motorical/mcp). Other agents (ChatGPT, Codex, Cursor, VS Code, any MCP client): the setup for each is on the hosted server page. This is the hosted MCP server: no install and no key. The npm package @motorical/mcp is a different, local option for API-key setups, and @motorical/cli is retired.
Pick your route
| What you want | Take this route |
|---|---|
| Try Motorical first, no domain yet, or nobody at the keyboard | Path 1: the sandbox. Instant, no DNS. Real sends reach only your own address and people who confirm by emailed link. |
| Send from a domain you own and plan to keep | Path 2: a Free account with your own domain. Publish the DNS records, then send. |
| Already on a plan and ready for production | Convert the sandbox onto your verified domain (motorical_sandbox_convert), then manage Motor Blocks. |
| Send from your own app's code | The HTTP API or SMTP. No MCP is needed. |
| You are building an app that implements an OAuth client | The signup server (motorical_signup_handoff). Not for chat agents. |
No Motorical account yet? Connect as above: the sign-in page offers account creation, MFA is required, and consent resumes by itself afterwards. No credential is returned to the agent. The hosted server also has a dedicated, unauthenticated signup audience exposing only motorical_signup_handoff; that one is for apps that implement an OAuth client (it needs that client's id, registered redirect URI, PKCE challenge and resource), not for chat agents. See Hosted MCP Resource Server for details. There's no local-server equivalent: a local install already has some credential configured, which is the scenario this bridges past.
Not sure which one you want: if your client supports remote MCP servers with OAuth (Claude Code, Claude.ai connectors), start with the hosted server — nothing to install, nothing to store, and it's the only path for a zero-credential cold start. If you need allowlisting by 6-digit code, browser handoff, unmasked PII, or a client that only speaks local stdio servers, use the local server.