MCP client configuration

Choose your host: Claude Code, Codex, Hermes, or Claude web/mobile. These hosted connections use an existing account. For a brand-new account, complete signup first; for a pending signup, resume it.

For an existing-account inbox request, verify whoami, select the intended project with mailbox:create, and create the inbox. Selected-inbox access does not cover a newly created inbox. No Full account control is required. Installing a plugin does not authorize sending.

For hosted email workflows without account administration, use the email assistant connection at https://mcp.extrovert.dev/assistant/mcp. It accepts OAuth and permits selected inboxes or project reach. The /mcp and local configurations below expose the complete customer tool surface, with permissions still explicitly granted.

Call agent_context only if it is in the current tool catalog. With no Extrovert MCP, fetch the public HTTPS contract; see the public update check. For supported hosts with local execution, use:

npx --yes --prefer-online @extrovert.dev/mcp setup --host auto

Automatic selection prefers hosted MCP. If more than one host is detected, select the intended host and use --transport hosted. Setup alone does not sign in: follow the returned native login command or host OAuth action (Claude Code: /mcp), and have the person sign in and approve access. Only then reload the connection when required and call whoami in that actual session. Configuration saved does not mean tools are loaded or the account is authenticated. Explicit adapters are below.

Add --json for an automation-readable result. host_reload_required means configuration is saved but the host connection is still pending; human_action_required means the returned terminal or sign-in step needs the person. Follow next_action and report the pending step. A successful CLI whoami or doctor checks that CLI profile; it does not prove that the agent host has loaded Extrovert. Confirm completion with the Extrovert MCP whoami tool in the reloaded session.

For an existing console account, use Extrovert’s hosted, stateless Streamable HTTP endpoint when the client supports OAuth:

https://mcp.extrovert.dev/mcp

OAuth-capable clients discover the authorization server, open browser sign-in and consent, and store and refresh the grant. No Extrovert key goes in the client configuration.

For local stdio, run npx --yes --prefer-online @extrovert.dev/mcp auth login to sign in to an existing account. The CLI stores and refreshes that separate connection privately for the selected profile. SSH and non-interactive agents can use the hosted completion page. Existing agent keys and enrollment keys remain supported. Offer sign_up only for an intended new account when live context or GET /v1/signup-status reports enabled. Preserve existing accounts and profiles. See human verification for unattended setup and missing-code recovery.

Hosted MCP permissions

Consent selects Personal assistant or Dedicated agent, resource reach, and separate actions. Selected inboxes exclude future additions; Project and Organization include them within that boundary. Full account control is explicit, defaults to 24 hours, and offers Until revoked. Refresh never extends the original expiry. Created credentials survive independently. Reuse working hosted OAuth connections; a release alone does not require reconnecting. See the access model. Hosted MCP also accepts scoped agent keys. Independent ev_credential_... credentials are API-only; use them with local stdio/CLI or an SDK. Hosted MCP rejects enrollment keys.

Try it with zero setup

Drop EXTROVERT_API_KEY and add "EXTROVERT_MOCK": "1" to any snippet below. The server boots against deterministic fixtures, so you can click through every tool: including wait_for_email: fully offline, no key, no network.

Run the package

Requires Node >= 20.

# stdio: for local hosts
npx -y @extrovert.dev/mcp

# CLI/setup commands from the same package
npx -y @extrovert.dev/mcp --help

# self-hosted: stateless MCP Streamable HTTP at /mcp (default :8787)
npx -y @extrovert.dev/mcp --http --port 8787

Codex

For ordinary email, prefer the assistant plugin with six skills and hosted MCP:

codex plugin marketplace add extrovert-dot-dev/extrovert-skills
codex plugin add extrovert-assistant@extrovert

Use one plugin per session. Preserve working full-profile installations, pins, local edits and host scope; do not migrate or install duplicates automatically. If plugins are unavailable, use the standalone assistant skills and hosted OAuth below.

Hosted OAuth

For an existing account, no local Node.js runtime is needed:

codex mcp add extrovert --url https://mcp.extrovert.dev/assistant/mcp

mcp add can start authorization automatically. Finish that flow; do not launch a second concurrent login. If authentication remains broken, use:

codex mcp login extrovert --scopes extrovert:connect

Start a new Codex session, refresh hosted tool discovery, and verify MCP whoami and intended inbox access. An Unknown CLI auth label is inconclusive when authenticated native tools work. Hosted users need no local MCP package upgrade for a server fix. Check that all six skills are discoverable after reload; until then report reload pending, not setup complete. If you need workflow skills, install only the core skills. That optional installer requires Node.js; hosted MCP does not. When local installation is unavailable, use the linked task guides without installing an SDK.

Plugin with skills and local MCP

The optional complete plugin includes the full skill pack and packaged stdio MCP server:

codex plugin marketplace add extrovert-dot-dev/extrovert-skills
codex plugin add extrovert@extrovert

This plugin runs @extrovert.dev/mcp locally and requires Node.js 20+. For a requested new account, use agent-first signup in that same local profile instead of starting existing-account OAuth.

For this local plugin, run the CLI’s existing-account login in its intended profile, then start a new Codex session and call whoami. If setup instead received an enrollment key, call redeem_enrollment; the packaged server stores the returned agent key.

To configure only MCP, without the skills bundle:

npx --yes --prefer-online @extrovert.dev/mcp setup --host codex --transport stdio

Hermes

Use the intended Hermes profile throughout. If you are creating a brand-new account, finish signup in that profile first, then use local stdio with the saved credential. Do not start hosted OAuth for a pending signup.

For an existing account, configure hosted MCP and authenticate:

npx --yes --prefer-online @extrovert.dev/mcp setup --host hermes --transport hosted
hermes mcp login extrovert

The setup helper requires Node.js 20+, not a compiler or source checkout. It preserves existing configuration. Reuse a working connection rather than adding another. Follow Hermes’s reload instructions and verify MCP whoami and inbox access; CLI login alone does not verify native tools.

Hermes uses standalone skills for this path, not Claude’s marketplace command. Install the core skills into the same intended host/profile, unless already present. Do not install the admin pack for ordinary inbox work. If local installation is unavailable, use the HTTPS route when private execution is supported; otherwise report the required setup step rather than installing a developer toolchain. See local stdio and enrollment alternatives.

Claude Desktop local server

For remote OAuth chat, use the email assistant connection or add the full /mcp URL through Claude’s custom connector controls. The local configuration below runs only on this computer; it is not the Claude Mobile or cloud-backed Cowork installation path.

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

claude_desktop_config.json

{
  "mcpServers": {
    "extrovert": {
      "command": "npx",
      "args": ["-y", "@extrovert.dev/mcp"]
    }
  }
}

Running from a local checkout instead of npm:

claude_desktop_config.json (local checkout)

{
  "mcpServers": {
    "extrovert": {
      "command": "node",
      "args": ["/absolute/path/to/extrovert/mcp/dist/bin.js"]
    }
  }
}

Claude Code

Install skills and hosted MCP together

For a new account, finish signup first. For an existing account, use the following hosted plugin; no local runtime is needed.

Inside Claude Code, add our self-published marketplace and install one plugin:

/plugin marketplace add extrovert-dot-dev/extrovert-skills
/plugin install extrovert-assistant@extrovert

Assistant includes the selected email skills and hosted email tools, without account administration or commerce. For the complete customer skill and tool surface, use /plugin install extrovert-full@extrovert instead. Full still requires explicitly granted permissions; installing it does not grant Full account control.

Choose one plugin, not both. These plugins include hosted MCP: no Node.js, npm package, separate skills installation, or additional claude mcp add is required. If you already have a working Extrovert connection or standalone skills, preserve them and avoid duplicate registrations; switching installation methods is optional.

Restart Claude Code after installation, then use /mcp to select the plugin’s Extrovert connection and complete browser sign-in and consent. Ask the agent to call whoami and verify intended inbox access through that connection.

The @extrovert suffix identifies our marketplace, not an npm release tag. Plugin files come from the published GitHub marketplace; MCP runs on our hosted service. See update commands. This is not an Anthropic directory listing or a Claude Mobile install command.

Connect only MCP

Add the hosted endpoint, then use /mcp inside Claude Code to complete the browser OAuth flow:

claude mcp add --transport http extrovert https://mcp.extrovert.dev/mcp

For local stdio instead:

npx -y @extrovert.dev/mcp setup --host claude

Or connect to a deployment you operate over HTTP (pass your limited key as a bearer header):

claude mcp add --transport http extrovert https://your-mcp-host.example/mcp \
  --header "Authorization: Bearer pk_agent_..."

Cursor

~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

stdio

.cursor/mcp.json

{
  "mcpServers": {
    "extrovert": {
      "command": "npx",
      "args": ["-y", "@extrovert.dev/mcp"]
    }
  }
}

hosted OAuth

.cursor/mcp.json

{
  "mcpServers": {
    "extrovert": {
      "url": "https://mcp.extrovert.dev/mcp"
    }
  }
}

What key to use

Use OAuth for the hosted endpoint. The packaged stdio server loads a limited agent key from the local credential store and writes the full replacement after verify_signup or redeem_enrollment. EXTROVERT_API_KEY remains an explicit override. Use the access deliberately chosen for this runtime; broad administration is an explicit setup choice, not a repair for ordinary inbox access. See Authentication & keys.

On Linux and macOS the default file is ~/.config/extrovert/credentials.json (or $XDG_CONFIG_HOME/extrovert/credentials.json); Windows uses %APPDATA%\Extrovert\credentials.json. The directory is owner-only and the file is mode 0600 on Unix. Override the directory with EXTROVERT_CONFIG_DIR for an isolated or managed runtime.

Do not put an administrative key in host config

Host config files are easy to leak (synced dotfiles, screen shares, support bundles). Prefer the credential store or hosted OAuth. If an explicit key is required, use a limited agent key and rotate it if exposed. Pass an enrollment key only to the packaged local server for redemption, never to hosted MCP.

Next

• MCP overview & tools: the full tool list and security model.
• wait_for_email: wait for a matching incoming message.
• Authentication and keys: permissions and key reach.