Wire it into an agent host

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@next`
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@next --http --port 8787`

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

Minimal host config

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

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

For Extrovert’s hosted OAuth endpoint:

{
  "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:

{
  "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.

The key the host holds

Use hosted OAuth, supply a limited pk_agent_… key, or give the packaged stdio server a short-lived pk_enroll_… key to redeem. Do not provide an organization-wide administrative key.
limited credentials only
Local stdio reads its permission-restricted credential file. EXTROVERT_API_KEY is an explicit override; a self-hosted HTTP client uses an Authorization header.
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.

The tool-call loop

Once connected, the agent uses ordinary tool calls. A typical 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" → the human released it
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 blocks server-side and returns the OTP and verification link already extracted, so the agent can continue without its own polling loop.

Environment

Variable	Default	Purpose
`EXTROVERT_API_BASE_URL`	`https://api.extrovert.dev`	Base URL of the Extrovert REST API.
`EXTROVERT_API_KEY`	(empty)	Limited agent key (`pk_agent_…`) or an enrollment key for local redemption (`pk_enroll_…`).
`EXTROVERT_CONFIG_DIR`	platform config directory	Override the local credential directory.
`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.

Client configuration: per-host config files.
MCP overview & tools: the full tool list and security model.
wait_for_email: the blocking primitive, in depth.