MCP overview and tools
@extrovert.dev/mcp exposes Extrovert through the Model Context Protocol. Use the hosted endpoint with
OAuth when the client supports remote MCP, or run the packaged server over stdio for a local host.
This page describes the complete customer tool surface. The hosted
email assistant connection uses /assistant/mcp and a
smaller, explicit catalog for email, review, and owned-domain workflows. It excludes
commerce, credential export, webhooks, and general administration; use the tools
actually listed by your connection. Both routes preserve your resource and role
boundaries.
get_inbox also exposes human_email_review, the default-off option to
email your own human without review.
It requires exactly one To recipient at the verified human email, no Cc/Bcc or aliases.
Writing rules and sending limits still apply. Other recipients keep their usual policy.
Ordinary agents cannot enable it; human administration or explicit Full account control can.
https://mcp.extrovert.dev/mcpConnect and identify the key
Section titled “Connect and identify the key”| Tool | Purpose |
|---|---|
agent_context | Read current release information, skill digests, guides, and signup availability |
sign_up | Start self-signup when the platform gate is enabled |
verify_signup | Exchange the temporary verification-only key for the durable key |
redeem_enrollment | Create or find an agent by stable handle and return its limited key |
whoami | Read the actual identity, resource reach, expiry, and permissions |
Hosted OAuth avoids pasting a key into client configuration. Local stdio stores the durable key in a permission-restricted credential file after successful enrollment or signup verification.
Hosted OAuth asks you to choose Personal assistant or Dedicated agent, then select inboxes, a project, an organization, or Full account control. Actions are granted separately. Selected inboxes is the recommended default and excludes future inboxes. Project and organization choices include future resources within that boundary. Your current organization role remains the upper limit; sign-in alone does not grant permissions.
Ordinary email setup needs limited mail permissions. Full account control is an explicit option for account administration. It can administer your customer account, use other agents’ inboxes, change access and policies, create credentials, and approve requests, including its own. It expires after 24 hours by default, with an explicit Until revoked alternative. Token refresh never extends that deadline. Credentials it creates, including administrative credentials, survive independently until separately expired or revoked.
Use Connections in the account menu to review reach, expiry, activity, and created access.
Revoking a parent connection does not revoke its created credentials. Private platform-operator
access is excluded. Legacy hosted sign-ins must reconnect once through the new consent flow;
existing limited pk_agent_... keys continue to work.
Enrollment and API keys serve different jobs. An enrollment key creates an agent during setup. An API key connects an existing agent.
For a task-based walkthrough from interactive setup to deployed workers, read Connections and access.
Administrative actions
Section titled “Administrative actions”These tools require explicit Full account control for execution. Discovery itself only reads API metadata; it does not expand a connection’s permissions.
| Tool | Purpose |
|---|---|
list_administrative_actions | Search a bounded page of customer administrative actions; follow its cursor for more |
describe_administrative_action | Inspect exact path, query, and body schemas before executing |
read_administrative_action | Execute a GET action such as adminMe to find currently administered organizations |
change_administrative_action | Configure projects, agents, credentials, billing, policies, and review approvals |
Read and change tools are separate. All actions retain server-side role checks and delegated attribution. Changes are never automatically retried: read state after an ambiguous result before trying again. Created credentials are returned once and survive independently; store them privately and revoke them separately in Connections.
The packaged CLI provides extrovert admin actions, admin describe, admin read, and
admin change --input-stdin. The TypeScript SDK provides the same catalog and a typed
client.administration.call(actionId, input) method. Ordinary scoped agent keys cannot execute
administrative actions. Streaming uses the dedicated event-stream tools rather than this action catalog.
Inbox tools
Section titled “Inbox tools”| Tool | Purpose |
|---|---|
create_inbox | Create an inbox with optional username, domain, webhook, metadata, and idempotency id |
list_inboxes | List inboxes in the key’s allowed breadth |
get_inbox | Read one inbox and its effective review policy |
update_inbox | Change display name, webhook, metadata, or permitted fields |
export_email_config | Export portable IMAP and SMTP configuration when the key and plan allow it |
delete_inbox | Permanently remove an inbox and its messages |
create_inbox returns an opaque inbox id and an address. Use the id for durable references.
Mail and conversation tools
Section titled “Mail and conversation tools”| Tool | Purpose |
|---|---|
send_email | Submit a new message under the inbox’s review policy |
reply_email | Reply by message or thread, with optional reply-all |
forward_email | Forward a message to new recipients under the same review policy |
read_messages | List a bounded page of message headers and bodies |
get_message | Fetch one message and choose source or extracted presentation |
search | Search one inbox or all inboxes the agent owns |
list_threads, get_thread | Read conversation summaries and full history |
mark_read | Set one message’s read state |
batch_update_messages | Change read state or folder for up to 200 messages |
delete_message, delete_thread | Move content to Trash or permanently expunge it |
list_attachments, get_attachment | Inspect attachment metadata, then download one part |
wait_for_email | Block for a matching message and return OTP or verification-link extraction |
get_message accepts format: auto | text | html | both and
variant: source | extracted. Source text and html are independent MIME alternatives. Their
extracted_text and extracted_html derivatives are nullable and best effort.
Review Loop tools
Section titled “Review Loop tools”Every agent-plane send, reply, and forward follows effective_review_policy. New accounts use
require_review. Under that policy, outbound calls need intent.summary and normally return
queued_for_review with an rr_... id. A missing intent returns 422 intent_required; nothing is sent
or queued.
| Tool group | Tools |
|---|---|
| Review records | list_reviews, get_review, get_review_turns, get_review_feedback |
| Agent revisions | post_review_chat, submit_revision, cancel_review, restamp_review |
| Durable events | list_review_events, wait_for_review_event, ack_review_event |
| Reviewer agent | get_review_decision_context, reviewer_decide |
| Categories | list_categories, get_category, propose_category, update_category |
| Graduation and pacing | get_risk_dial, get_graduation_status, get_backlog_status, get_pacing_state, propose_graduation |
| Writing rules | get_rules, learn_review_rule, save_rule (project maintenance), promote_rule, retire_rule, get_rule_audit, undo_rule_change |
Human authority remains separate. Agents may propose categories and graduation, but humans control the
effective review policy, risk settings, graduation decisions, and final approval where configured.
A reviewer agent also needs review:act and an active link for the specific inbox or category. It does
not receive the composing agent’s send permission.
Use a stable client_id on MCP outbound and review mutations. After a transport timeout, reuse the
same value for the same exact intent. Do not reuse it for different content.
Webhooks, contacts, suppression, and deliverability
Section titled “Webhooks, contacts, suppression, and deliverability”| Area | Tools |
|---|---|
| Webhooks | register_webhook, list_webhooks, get_webhook, update_webhook, delete_webhook |
| Contact lists | add_contact_list_entry, list_contact_lists, delete_contact_list_entry |
| Suppression | check_suppression, list_suppressions, revoke_suppression |
| Deliverability | get_deliverability_status, list_deliverability_findings |
Webhook secrets are returned once. Verify the signature over the raw request body before parsing or trusting the event. Contact-list and suppression checks apply again at delivery after review.
Domains, jobs, and commerce requests
Section titled “Domains, jobs, and commerce requests”| Area | Tools |
|---|---|
| Domain readiness and updates | list_domains, get_domain, wait_for_domain, list_domain_events |
| Connect and manage domains | onboard_domain, verify_domain, offboard_domain |
| Async work | get_job |
| Quotes and requests | quote_domain, request_domain_purchase, request_plan_change |
| Request recovery | get_commerce_request, list_commerce_requests, cancel_commerce_request |
commerce:request lets an agent quote, request, inspect, and cancel its own eligible pending request.
It never approves payment or grants spending authority. Surface the exact blocker, next action,
approval URL, and recommended poll interval to the human.
stream_info reports the current event-stream connection details. Streams and webhooks reduce polling
latency, but durable review events still require list or wait plus acknowledgement.
Tool annotations and key boundaries
Section titled “Tool annotations and key boundaries”Tools declare read-only, destructive, idempotent, and open-world hints so the host can present them appropriately. These hints do not replace server authorization.
The key’s fixed organization, project, permissions, ownership, and resource breadth are checked on every request. A project id in tool input is an assertion and cannot switch projects.
Transports
Section titled “Transports”| Transport | Use it for | Connection |
|---|---|---|
| Hosted Streamable HTTP | Remote OAuth-capable clients | https://mcp.extrovert.dev/mcp |
| Local stdio | Hosts that start a child process | npx -y @extrovert.dev/mcp |
| Self-operated Streamable HTTP | A packaged MCP deployment you operate | npx -y @extrovert.dev/mcp --http --port 8787 |
Set EXTROVERT_MOCK=1 for deterministic offline fixtures. Mock mode is for integration development and
does not prove live delivery.
- MCP client configuration
- Wire an agent host
- MCP
wait_for_email - Review Loop agent contract
- Purchase approvals for agents
When an inbox list and lookup disagree
Section titled “When an inbox list and lookup disagree”Call whoami through the connection you are diagnosing. Compare agent_id,
key_id, auth_method, key_tier, inbox_scope, org_id, and project_id when
checking hosted MCP against a local CLI profile. A matching account name does not
mean the credentials have the same access.
Use list_inboxes with an exact domain filter when needed. Org-tier keys must
also select a project or wildcard: true. Follow next_cursor with the same
filters until there are no more pages. Empty results describe only that
connection’s scope and filters; a malformed response or service failure is not
an empty inventory.
If get_inbox succeeds but a complete list under the same connection and breadth
omits that inbox, report the inconsistency with the response request IDs. Do not
assume there is a separate hidden-address permission.
Inbox status, sender verification, and send-review policy describe different things. Missing sender verification is unavailable information, not evidence that setup is pending. Follow the send tool’s review workflow and explicit errors when the user asks to send.
Project and organization owners/admins can optionally skip review for email between agents. Both settings start off and require every recipient to belong to the sender’s enabled project or exact organization. Discover the current choices through get_inbox.internal_email_review (SDK: inbox detail), then submit normally. Writing rules and sending limits still apply; this grants no additional inbox access.