Connect an agent

Set up authentication

Use a client that supports remote MCP Streamable HTTP and OAuth authorization code with S256 PKCE. Configure its server URL as https://donespan.com/mcp.

1. Discover https://donespan.com/.well-known/oauth-protected-resource and its authorization-server metadata. Use the exact discovered resource: https://donespan.com. The transport path is not part of the resource identifier.
2. Register a public client at /oauth/register with an exact redirect URI. Generate a verifier, S256 challenge and callback state; open the advertised authorization endpoint in the customer's browser.
3. Request only needed scopes. For booking:approve, include booking_max_total_cents in the authorization request (for example, 25000 means $250.00 per visit). The customer signs in with Google and reviews DoneSpan's consent screen. Exchange the returned code using the verifier, same redirect URI and resource. Never collect Google credentials in the agent.
4. Send the access token as a Bearer credential. Access tokens last at most one hour; refresh can narrow scopes. Grants last up to 30 days and may be revoked sooner.

A deployed HTTPS origin, configured Google login and OAuth storage are required. The local test configuration does not establish production readiness.

Admin Agent

Operators can connect a separate administrative Agent at https://donespan.com/mcp/admin. It uses the same OAuth/PKCE flow but accepts only ops:read, ops:review and ops:recovery; customer and operator scopes cannot be mixed. The operator must pass the linked Cloudflare Access check on the consent screen.

The eight tools cover the operations inbox, provider-review evidence, cases, workflow status, review assignment/update, evidence-review recording and confirmed workflow recovery. Every mutation requires a reason, version and idempotency key and is audited. The Agent cannot activate providers, reject providers, close cases, send messages, access raw evidence files or move money. Manage or revoke grants at Connected admin agents.

Supported capabilities

check_serviceability

Coverage only. Public REST equivalent: GET /api/v1/serviceability?postal_code=98036. MCP transport requires authentication.

jobs:create

create_job saves a draft without contacting providers.

jobs:read

get_job, get_offers and get_booking read owned persisted state.

quotes:request

request_quotes contacts eligible enrolled providers only with recorded outreach consent.

booking:propose

prepare_booking and request_booking_change prepare customer review.

booking:approve

approve_booking creates a pending booking only after the Agent displays the exact final quote and the user clicks confirm, and only when the quote is within the authorized maximum.

A request-to-approval journey

1. Check coverage. Call create_job with {"intake":{"postal_code":"98036"},"idempotency_key":"example-draft-001"}. This deliberately incomplete draft returns missing_fields; the customer completes it in the website. Keep its resource ID.
2. After the customer consents to outreach, call request_quotes with job_id, expected_version, idempotency_key, outreach_consent: true and consent_version: "quote_outreach.v1". Persist the returned ID and status URL. Disconnecting does not stop the durable work.
3. Poll get_job/get_offers at next_poll_after_seconds. Review current confirmed quotes. Call prepare_booking with job_id, current expected_version, offer_id and idempotency_key.
4. If the grant includes booking:approve and the quote is within its limit, show the exact scope, price, schedule and address-disclosure consequence in the Agent UI, obtain one explicit user confirmation, and call approve_booking. Otherwise give approval_url to the customer for the first-party confirmation page.
5. Read get_booking after reconnect. PENDING_PROVIDER is not CONFIRMED. Change requests leave the original booking intact while review, customer approval and any required provider reconfirmation proceed.

Retries and revocation

Use a stable 8–128 character idempotency key for each mutation. Letters, digits, dots, underscores, colons and dashes are accepted. REST uses the Idempotency-Key header; MCP uses idempotency_key. Identical commands share replay protection across transports within the same grant. A changed payload with the same key conflicts.

After reauthorization, read saved IDs before creating anything again: a new grant has a new key namespace. Inspect error.code and error.retryable before retrying. MCP command failures use isError and an error JSON text item; authentication failures return HTTP 401. Resolve relative REST status/approval links against this application origin.

Revoke access in Connected agents. Revocation blocks reads, writes, replay and refresh. It does not cancel previously authorized work. A 401 requires reauthorization; a 403 indicates missing permission or an action unavailable to agents.

Verification status

Local synthetic tests cover native browser consent/callback/revocation and persisted MCP/REST commands using protocol 2025-11-25. Implementation versions: Agents 0.23.0, MCP server SDK 2.0.0, Cloudflare OAuth Provider 0.10.3.

AT18 still requires a named and versioned independently operated user-owned client, real identity login, disconnect/reconnect, customer approval handoff and revocation evidence. The OpenAPI document covers public catalog and delegated/customer capability routes; provider/operator and customer-only action contracts remain outside it.