Use DoneSpan with an AI 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 through DoneSpan and reviews its consent screen. Exchange the returned code using the verifier, same redirect URI and resource. Never collect the customer's sign-in 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 customer sign-in and OAuth storage are required. The local test configuration does not establish production readiness.

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:update

update_job replaces saved DRAFT request fields using the current version. It cannot edit after provider outreach begins. Existing create-only grants need new consent for this separate permission.

jobs:read

get_job, get_offers, get_booking_readiness, get_booking and get_execution_report read owned persisted state. Readiness contains no private address data. Reports are read-only; feedback remains a first-party customer action.

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 incomplete draft returns missing_fields. With jobs:update, read the saved fields, ask the customer for missing details, then call update_job with job_id, expected_version, the complete replacement intake and a new idempotency_key. Otherwise follow the customer 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. After selecting a quote, read get_booking_readiness with job_id and offer_id. Give its handoff_url to the customer to enter the private address. On await_address_review, wait at the returned interval; the customer can return later. A withdrawn quote may require repricing or be unsupported. When next_action is prepare_booking, prepare with the current version and a new idempotency key. A readiness read never creates a proposal.
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.

Run the developer connection check

From the repository after npm ci, use Node 24.11 or newer and run node --experimental-strip-types scripts/agent-connection-check.ts. Provide DONESPAN_ORIGIN and the already consented DONESPAN_ACCESS_TOKEN through your environment. Keep tokens out of logs and source files.

The official MCP client SDK discovers the server, lists tools, checks coverage, disconnects and reconnects. It performs no mutations and uses normal HTTPS certificate validation. It is a developer diagnostic; customer sign-in and named third-party app acceptance are separate checks.

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, delegated reads/writes and the customer-owned execution-report read; provider/operator and customer-only write contracts remain outside it.