# Duey MCP server — guide for AI agents

> Schedule, preview, pause, and cancel Duey Sessions — the cloud writer that types your draft into Google Docs with a realistic edit history — plus the Duey Humanizer and AI detector.

## Connect

- Server URL: https://app.duey.ai/api/mcp
- Transport: Streamable HTTP
- Auth: OAuth 2.1 + PKCE with Dynamic Client Registration. The user approves once on a Duey consent screen; no API keys.
- Human install guide: https://app.duey.ai/mcp

## How to use it well

1. **Check the account first.** Call `get_account_status` when you don't know the user's plan or whether Google Drive is connected. If Drive isn't connected, send the user to https://app.duey.ai/sessions to connect it — tools that write to Google Docs fail until they do.
2. **Get the deadline right.** Ask for (or infer) the deadline and pass it as ISO 8601 with the user's UTC offset in `deadline_at`. If the user says when writing may happen, pass `work_hours` with their IANA timezone (paid plans only).
3. **Preview before you commit.** Call `preview_session` with the same arguments before `create_session` when the deadline is tight or the user asks whether it will finish in time. If it reports `feasible: false`, suggest a later deadline.
4. **Keep the formatting.** Pass `format: "markdown"` to `create_session` whenever the text has headings, lists, bold or italics, so they become real Google Docs formatting instead of symbols.
5. **Write into the right doc.** To add to an existing doc, find it with `list_recent_docs` and pass its `document_id` as `existing_document_id`. Otherwise a new doc is created.
6. **Manage running sessions.** Use `list_sessions`, `get_session_status`, `pause_session`, `resume_session` and `cancel_session`. Resuming shifts the rest of the schedule and the deadline by the pause length.
7. **Humanizer and detector.** `humanize_text` takes 100–5000 words; free accounts get one run per day. Use `detect_ai_text` before and after to check the result.
8. **Handle errors.** Failures return `{ ok: false, error, message }` with a stable `error` code (below). Relay the `message`, and any `upgrade_url` or `connect_url`, to the user rather than retrying.

## Tools

- `create_session` — Schedule a Duey Session over hours, days, or weeks.
- `preview_session` — Check when a session would finish before creating it.
- `list_sessions` — Show all your scheduled, running, and completed sessions.
- `get_session_status` — Check progress on a specific session.
- `cancel_session` — Cancel a scheduled or running session.
- `pause_session` — Pause a scheduled or running session.
- `resume_session` — Resume a paused session; the deadline shifts by the pause length.
- `list_recent_docs` — List your recently-touched Google Docs to attach to a session.
- `get_session_transcript` — Read the source text that a session is typing into Google Docs.
- `humanize_text` — Rewrite AI-generated text to read as human-written (100–5000 words).
- `detect_ai_text` — Score whether text reads as AI-written. Primary detector with backup fallback.
- `get_account_status` — Read your subscription tier, free trial state, and Drive connection status.

## Prompts

- `schedule_writing` — Guided flow: check the account, preview the deadline, create the session.
- `humanize_and_check` — Score text, humanize it if needed, and re-check.

## Error codes

| `error` | Meaning / what to do |
|---|---|
| `drive_not_connected` | Google Drive isn't connected. Send the user to `connect_url`. |
| `missing_deadline` | Normal mode needs `deadline_at`. |
| `invalid_deadline` | `deadline_at` isn't valid ISO 8601. |
| `invalid_work_hours` | End hour not after start hour, or unknown timezone. |
| `plan_error` | The schedule can't be built, e.g. the deadline is too close. Suggest a later one. |
| `free_trial_exhausted` | The free Session trial is used up. Share `upgrade_url`. |
| `free_tier_limit` | Free trial limit hit (length or mode). Share `upgrade_url`. |
| `asap_paid_required` | ASAP mode needs a paid plan. Use a deadline instead. |
| `asap_in_flight` | An ASAP session is already running. |
| `not_found` | No session with that id for this user. |
| `not_pausable` | Only scheduled or running sessions can be paused. |
| `not_paused` | Only paused sessions can be resumed. |
| `docs_error` | Google Docs rejected the write. `retryable` says whether to try again. |
| `payment_required` | Free Humanizer tries used up for today. Share `subscribe_url`. |
| `invalid_word_count` | `humanize_text` needs 100–5000 words. |
| `moderation_blocked` | The text was refused by content moderation. |
| `rate_limited` | Too many calls. Wait `retry_after_seconds` (or the Retry-After header). |
| `detector_unavailable` | Both AI detectors failed. Try again later. |
| `drive_error` | Google Drive couldn't list the user's docs. Try again later. |
| `no_source_text` | That session has no stored source text. |
| `decrypt_failed` | Stored source text couldn't be read (server-side issue). |
| `parse_failed` | `humanize_text` couldn't split the text into paragraphs. Clean up the formatting. |
| `humanizer_failed` | The Humanizer errored mid-run. Try again. |
| `empty_result` | The Humanizer returned nothing. Try again. |
| `internal_error` | Unexpected failure. Apologize and try again later. |

## Machine-readable metadata

- MCP descriptor: https://app.duey.ai/.well-known/mcp.json
- Protected resource metadata (RFC 9728): https://app.duey.ai/.well-known/oauth-protected-resource
- Authorization server metadata (RFC 8414): https://app.duey.ai/.well-known/oauth-authorization-server

Support: hello@duey.ai