Wire it into an agent host

For the shortest path, start at Set up your agent: agent handoff, existing-account connection, manual commands, and private scoped-key installation.

The Extrovert MCP server works with hosts that support the Model Context Protocol. This page covers the connection and tool flow; for host-specific config files see Client configuration.

Two transports, one binary

Transport	Use it for	Command
stdio	Local hosts that spawn the packaged process.	npx -y @extrovert.dev/mcp
Hosted OAuth	Existing human console accounts in OAuth-capable hosts.	https://mcp.extrovert.dev/mcp
HTTP (Streamable)	A deployment you operate: POST /mcp, default :8787.	npx -y @extrovert.dev/mcp --http --port 8787

npx -y @extrovert.dev/mcp --help

Hermes: connect without editing configuration

Select the intended Hermes profile first so HERMES_HOME points to that profile, then run:

npx -y @extrovert.dev/mcp setup --host hermes --transport hosted
hermes mcp login extrovert

Finish browser sign-in and consent, start a new Hermes session, and call whoami. A saved config or successful browser callback is not proof that tools are connected. whoami confirms the account, project and available capabilities without exposing credentials.

For local stdio with existing-account browser login:

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

Use the same Hermes profile for each command. SSH/headless agents use the completion-code flow. Reload Hermes and call whoami there. Local login is separate from hosted MCP OAuth.

For an enrollment key instead:

npx -y @extrovert.dev/mcp enroll --agent-handle support-agent
npx -y @extrovert.dev/mcp setup --host hermes --transport stdio
npx -y @extrovert.dev/mcp doctor

Paste the key at the hidden prompt. The CLI saves it privately for the selected profile. Start a new Hermes session and call whoami there too: doctor checks the local credential, not the host’s session. Setup preserves other MCP servers and does not overwrite an existing Extrovert entry.

If approved OAuth still returns an authentication error, keep the non-secret request ID and contact support. Do not repeat browser approvals indefinitely. Local enrollment is a supported alternative when the account owner provides an appropriately limited enrollment key.

Minimal host config

Almost every MCP host uses the same mcpServers shape. For a local (stdio) host:

mcp config (stdio)

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

For Extrovert’s hosted OAuth endpoint:

mcp config (hosted OAuth)

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

For a self-hosted runtime over HTTP, point at your deployment and pass the key as a bearer header:

mcp config (hosted HTTP)

{
  "mcpServers": {
    "extrovert": {
      "url": "https://your-mcp-host.example/mcp",
      "headers": { "Authorization": "Bearer pk_agent_..." }
    }
  }
}

Copy-paste configs for Claude Desktop, Claude Code, and Cursor are in Client configuration.

One-command Codex setup

Install the complete plugin with codex plugin marketplace add extrovert-dot-dev/extrovert-skills followed by codex plugin add extrovert@extrovert, or configure only stdio with npx -y @extrovert.dev/mcp setup --host codex. Start a new session afterward.

The key the host holds

1. Use hosted OAuth or local CLI OAuth with explicit consent, a scoped pk_agent_... key, or an independently issued ev_credential_... credential. For a new agent, redeem an enrollment key locally. Choose access for the task: selected inboxes for mail, or project access with create permission when inbox creation is needed. Full account control is for explicitly requested administration, with a 24-hour default.

2. Local stdio reads its permission-restricted credential file and refreshes local OAuth within the original grant. EXTROVERT_API_KEY is an explicit override; a self-hosted HTTP client uses an Authorization header.

3. With an enrollment key, the host’s first tool call is redeem_enrollment, which creates or finds the agent and returns its project-bound key. The packaged stdio server stores that key automatically.

Host config leaks easily

Synced dotfiles, screen shares, and support bundles can expose host config. Prefer hosted OAuth or the packaged credential store; do not paste a durable key into JSON. If an explicit enrollment key leaks, revoke it instantly and in isolation without touching any other agent.

The tool-call loop

Once connected, the agent uses ordinary tool calls. Start with whoami and list_inboxes; use the existing inbox when appropriate. A new-agent enrollment, inbox, and review flow is:

redeem_enrollment { enrollment_token,
                    agent_handle }           -> project-bound agent key
create_inbox { display_name }                -> agent7@extrovertmail.com
get_inbox { inbox }                          -> ... effective_review_policy: "require_review"
send_email { inbox, to, subject, text,
             intent }                        -> queued_for_review { review: { id: "rr_..." } }
wait_for_review_event { review_id }          -> reason: "sent" -> confirmed sending outcome
wait_for_email { inbox, from }               -> { message, otp_code, verification_link }
reply_email { inbox, message_id, text,
              intent }                       -> queued_for_review (same policy applies)

Outbound mail is queued for a human by default, so it carries an intent (one sentence of reviewer context; without it the call is rejected 422 intent_required) and it finishes on a terminal sent / send_failed review event rather than at the moment the tool returns. Read effective_review_policy once and branch on it; an allow_direct inbox sends straight away.

Tools are annotated (readOnlyHint, destructiveHint, and related hints) so a host can present read tools freely and gate delete_inbox / delete_webhook behind confirmation. The standout is wait_for_email: it waits for a matching incoming message and returns it with any OTP code and verification link already extracted.

Environment

Variable	Default	Purpose
EXTROVERT_API_BASE_URL	https://api.extrovert.dev	Base URL of the Extrovert REST API.
EXTROVERT_API_KEY	(empty)	Scoped agent key (pk_agent_...), independent connection credential (ev_credential_...), or an enrollment key for local redemption (pk_enroll_...).
EXTROVERT_CONFIG_DIR	platform config directory	Override the local credential directory.
EXTROVERT_PROFILE	(unset)	Isolate one local agent’s credential from other agents.
HERMES_HOME	(host-selected)	Hermes profile directory; local Extrovert credentials stay in that profile.
EXTROVERT_MOCK	(off)	Set 1 to force offline fixtures: every tool works with no key, no network.
EXTROVERT_REQUEST_TIMEOUT_MS	30000	Per-request timeout for non-blocking calls.
EXTROVERT_MAX_WAIT_MS	300000	Upper bound the server allows wait_for_email to block.
PORT / HOST	8787 / 0.0.0.0	--http bind.

Validate offline first

Drop EXTROVERT_API_KEY and set "EXTROVERT_MOCK": "1" in any config above. The server boots against deterministic fixtures so you can exercise every tool, including wait_for_email, before you have a live key.

Next

• Client configuration: per-host config files.
• MCP overview & tools: the full tool list and security model.
• wait_for_email: wait for a matching incoming message.