# Resumable, owner-approved agent onboarding

Connect an MCP client to https://mailservicenow.com/api/mcp. This is the canonical OAuth resource; do not replace it with the Cloud Functions host or a preview URL. The service supports existing customer-domain hosted inboxes and can provision a new hosted inbox through the same resumable flow.

## 1. Owner approves one connection

The connector discovers `/.well-known/oauth-protected-resource/api/mcp` and `/.well-known/oauth-authorization-server`, then performs authorization-code OAuth with PKCE S256. The owner signs in with their verified Firebase identity, explicitly creates a customer account if needed, and approves an exact domain, mailbox and permission set. A pending service account can authorize setup; approval, domain ownership and an active hosted mailbox are still required before mail access.

For a complete setup-and-use connection, request `onboarding:manage mailbox:read mailbox:search mailbox:send mailbox:reply`. Optional `domain:read` and `domain:verify` permit `get_dns_instructions` and `verify_domain` for that exact domain. The owner may reduce the requested permissions. A scope error requires a new owner-approved connection for the missing permission; tools never silently expand access.

OAuth access tokens last five minutes. Refresh tokens rotate on use, expire after thirty days of inactivity, and cannot exceed the ninety-day grant lifetime. The server stores credential hashes. Tokens are exchanged only with the connector's OAuth transport, never returned by MCP tools. The connector platform controls its credential storage; Mail Service Now cannot guarantee storage in a particular installed plugin. Never paste OAuth tokens, API keys, SMTP passwords or DNS-provider secrets into a model prompt.

The built-in dynamic registration allowlist accepts exactly `https://chatgpt.com/connector_platform_oauth_redirect`, with matching RFC 9207 issuer identification in the authorization response. Additional clients require deployment-owner review of their exact redirect URI. There are no wildcard callbacks, arbitrary client-metadata URL fetches, or shared client secrets.

Legacy DNS-signup accounts and Firebase owner identities are not automatically merged by matching email or username. If a hostname is already claimed by another account, stop for an owner/support resolution; this flow cannot transfer it.

## 2. Start once, retain the onboarding ID

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"start_onboarding","arguments":{"idempotencyKey":"customer-agent-setup-001","domain":"example.com","localPart":"agent"}}}
```

Persist the returned `onboardingId`. Reusing the same idempotency key and input returns the same operation; changing domain or local part with that key returns an idempotency conflict. Only the approving owner and a connection scoped to the same target can read or resume it. Unknown and other-owner IDs receive the same not-found response.

The response separates `ownerOAuthApproval`, `accountIdentity`, `serviceApproval`, `domainOwnership`, `dnsReadiness`, `mailboxProvisioning` and `mailServerReadiness`. Follow `nextAction` and `retryAfterSeconds`. A pending service decision is never self-approved by the agent.

## 3. Review and publish exact DNS changes

`dnsReadiness.instructions.records` contains complete names, types, values, priorities and TTL suggestions. `dnsReadiness.diff` contains observed records, proposed additions, no-ops and owner-review conflicts. An unknown DNS observation is not permission to overwrite a record.

Publish the account-bound ownership TXT plus required MX, SPF and DKIM records. Preserve unrelated TXT records, existing authorized SPF senders and the owner's DMARC policy. Existing MX providers, multiple SPF/DKIM policies, conflicting selectors and CNAME records require review. Changing MX may interrupt the previous provider's inbound mail; the owner must approve the cutover.

This server does not have Cloudflare write access. Use an independently owner-authorized DNS-provider connector after presenting the exact preview, or hand the records to the owner. Never submit Cloudflare tokens to Mail Service Now. Authoritative publication and DNS propagation are separate from this service's verification.

## 4. Resume and renew without starting over

```json
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"resume_onboarding","arguments":{"onboardingId":"ob_0123456789abcdef0123456789abcdef"}}}
```

Resume rechecks live account approval, the current claim, ownership proof, DNS and the exact requested mailbox. Creating the hosted mailbox is transactional and idempotent. It does not change an existing forward-only/both mailbox into hosted mode or reset an existing mailbox password. A conflict needs owner review.

```json
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_onboarding_status","arguments":{"onboardingId":"ob_0123456789abcdef0123456789abcdef"}}}
```

This private status tool requires only the ID. It returns live state without changing DNS or mailbox state.

```json
{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"renew_onboarding_proof","arguments":{"onboardingId":"ob_0123456789abcdef0123456789abcdef"}}}
```

Renewal replaces an expired, unverified ownership proof while preserving the job. A valid or verified proof is retained. Publish the returned value before resuming. No agent credentials are rotated. Removed or transferred claims cannot be silently recreated by an old onboarding job.

`mailboxProvisioning.status=created` means the database mailbox exists. Live readiness additionally requires an exact current-configuration, revision-bound acknowledgement with a valid timestamp from the mail server, fresh successful sync/service health, and fresh conflict-free DNS checks. The legacy `mtaApplied` flag alone is insufficient; `mtaAppliedAt` is receipt metadata, not a delivery timestamp. If the server has not installed the acknowledgement-capable sync consumer, status remains awaiting apply. Even `ready=true` is configuration/service readiness, not proof of successful message delivery; `inboundDelivery=not_tested` remains explicit: this release does not implement an external delivery probe or a resync mutation. A real external test requires separate authorization; polling or an existing inbox message does not change this diagnostic into proof of delivery. Do not rotate keys, recreate the mailbox, or toggle modes to repair pending readiness. Installing the exact-ack consumer and storage collector on the mail host is a separately authorized rollout; source availability is not evidence of deployment.

## 5. Use the customer-domain inbox

These operations work on real stored mail for the approved customer-domain mailbox. The shared Mail Service Now product inbox is not included.

- `list_inbox`: read recent inbound message headers, optionally by folder; `mailbox` defaults to the exact approved address
- `get_message`: read one stored inbound message by `id` or `messageId` and mark it read; foreign IDs are not found
- `search_mailbox`: search sender, subject and body, with exact sender, direction, date and folder filters
- `send_mail`: send through the existing server SMTP path from the approved mailbox; one credit and existing rate/send controls apply
- `reply_to_message`: reply to a stored parent in that mailbox; derive recipient from the original stored sender and derive subject/references from the parent; an optional `to` must match. The inbound source does not currently preserve Reply-To, so this tool uses the sender

A hosted or both-mode mailbox has an inbox. A forward-only address does not. Each request rechecks the active account, current domain claim and mailbox; a staff role does not broaden the grant. OAuth credentials are refused by legacy REST endpoints and cannot call legacy key/password-issuing tools, arbitrary account/domain administration, or other mailboxes.

```json
{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"list_inbox","arguments":{"limit":25}}}
```

```json
{"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"search_mailbox","arguments":{"query":"invoice","direction":"inbound","limit":25}}}
```

```json
{"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"get_message","arguments":{"id":"inbound-document-id"}}}
```

```json
{"jsonrpc":"2.0","id":8,"method":"tools/call","params":{"name":"reply_to_message","arguments":{"id":"inbound-document-id","text":"Thanks, received."}}}
```

Send/reply examples are instructions for a separately authorized communication, not a request to send a test email. Mail sending itself is not idempotent: do not blindly replay after an uncertain SMTP result. Inbox pagination covers the newest 200 inbound rows. Search scans at most 200 inbound and 200 outbound rows; its `nextCursor` paginates that recent window and is bound to the mailbox/query. It is not a complete historical archive search. Outbound search covers stored replies; ordinary send_mail messages are not currently filed in the outbound store. Reading a reply parent marks that inbound message read.

## 6. Revoke only the intended agent

The owner opens https://mailservicenow.com/oauth-consent.html, signs in, selects the named connection and confirms revocation. Its access and refresh tokens stop working immediately; unrelated grants and legacy customer keys are unchanged. Refresh rotation is per grant. A replayed old code/refresh token invalidates its own grant family, not another client. Owner account deletion/recreation, session revocation, domain transfer or mailbox-generation replacement also invalidates the affected grant.

## Existing-mailbox diagnostics with an account key

For an existing mailbox, an account-key client can call read-only `get_mailbox_diagnostics` with a required `address` string. No onboarding ID is required. It is limited to the key's own account and existing mailbox; it does not accept an account selector or extend an OAuth grant. `get_account_status` retains account `ready` as approval and mailbox `ready` / `canSend` as send eligibility, with separate configuration, service-health and inbound-delivery evidence. Forward-only storage/inbox are `not_applicable`, and forwarding remains unverified/not_tested. Continue using `get_onboarding_status` for the owner-approved OAuth onboarding operation.

## Legacy status and compatibility

The old public `get_request_status` tool still requires `requestId` and either `email` or `username`; its input schema now declares that requirement. It intentionally coarsens negative states and never returns a key. The new private `get_onboarding_status` is the authenticated ID-only flow.

Legacy `request_access` and DNS-bound account-key recovery remain available for existing integrations. Legacy DNS recovery revokes all of that account's previous customer keys; it is not per-agent OAuth recovery. Use connection-specific OAuth revocation for the new flow.

The canonical endpoint implements sessionless Streamable HTTP with JSON responses, supporting MCP 2025-11-25 and 2025-06-18. Initialize with full protocolVersion, capabilities and clientInfo; send Content-Type: application/json and Accept: application/json, text/event-stream. Subsequent requests may include MCP-Protocol-Version for the negotiated revision. GET returns 405 because no SSE stream is offered; notifications receive 202 and do not execute tools. Send one message per POST, not a batch. The unsupported 2026-07-28 protocol is rejected rather than falsely advertised. The direct Cloud Function retains its older JSON-RPC discovery/batch compatibility route; that route is not the 2024 HTTP+SSE transport. Inspect tool errors as well as HTTP status. OAuth authentication failures return HTTP 401 and a `WWW-Authenticate` discovery challenge; insufficient OAuth permissions return HTTP 403. Canonical requests never run a batch. On the legacy direct-function compatibility route, every member of an OAuth batch has its method, tool and scope checked before any member runs; successful earlier application operations are not rolled back if a later operation fails for a state-dependent reason. Configure the connector for server-level OAuth. Tool-triggered account-linking UI is not claimed; authentication failures remain fail-closed HTTP 401/403 challenges.

References: [MCP authorization](https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization), [OpenAI connector authentication](https://developers.openai.com/plugins/build/auth).
