# Quotae MCP server

Connect an authorized agent to Quotae using Model Context Protocol over Streamable HTTP. The server endpoint is **https://api.quotae.app/mcp**. Authentication stays enabled for every tool, including tool listing. See the [Quotae API documentation](https://quotae.app/docs/) for onboarding and current rollout limits.

## Discovery and client configuration

- [Protected-resource metadata and scopes](https://api.quotae.app/.well-known/oauth-protected-resource/mcp)
- [Authorization-server metadata](https://api.quotae.app/.well-known/oauth-authorization-server)
- [MCP client configuration JSON](https://quotae.app/mcp.json)
- [OpenAPI description](https://quotae.app/openapi.json)
- [This page in Markdown](https://quotae.app/mcp.md)

The published configuration identifies the authenticated endpoint. It contains no secrets and does not grant access or establish a public ChatGPT listing. OAuth clients need preregistration and exact callback approval; changing a client ID locally cannot register a client. Use the authorization metadata to discover the OAuth flow.

## Available tools and required scopes

| Tool | Required scope | Action |
| --- | --- | --- |
| `quotae_get_context` | `account:read` | Read setup, currency, defaults and available actions |
| `quotae_search_clients` | `clients:read` | Find existing clients and addresses |
| `quotae_search_catalog` | `catalog:read` | Read saved catalogue items and prices |
| `quotae_list_quotes` | `quotes:read` | List quotes with status and private app links |
| `quotae_get_quote` | `quotes:read` | Read quote content and version |
| `quotae_create_quote_draft` | `quotes:drafts:write` | Create an explicitly requested unsent draft |
| `quotae_update_quote_draft` | `quotes:drafts:write` | Patch an eligible unsent, unshared draft |
| `quotae_get_operation` | `quotes:drafts:write` | Recover an uncertain draft operation |
| `quotae_list_invoices` | `invoices:read` | List invoices and payment facts |
| `quotae_get_invoice` | `invoices:read` | Read captured invoice details |
| `quotae_get_report` | `reports:read` | Read report totals for one currency |
| `quotae_get_report_entries` | `reports:read` | Read paginated records behind a report metric |

Every listed tool declares its input schema, output schema, annotations and required OAuth scope in `tools/list`. Tool presence does not imply permission to execute it. Tools return private account data only after token, ownership, scope and grant checks. Quote sending, invoice issuance, payments and deletion stay in Quotae.

## Verify an authorized connection

Use a compatible MCP client with a valid, owner-approved OAuth access token. Follow the MCP lifecycle:

1. Connect to the endpoint with `Authorization: Bearer <access-token>` and `Accept: application/json, text/event-stream`.
2. Send `initialize` with a supported protocol version and your client capabilities. Complete the `notifications/initialized` handshake and use the negotiated protocol version for subsequent HTTP requests.
3. Request `tools/list`. Expect the twelve tools above and their schemas. This read does not create or send documents.
4. With `account:read`, call `quotae_get_context` with `{}` and check the account currency and available actions. Stop if the account or permissions differ from what the owner approved.

An unauthenticated request returns HTTP 401 and a `WWW-Authenticate` header whose `resource_metadata` points to the protected-resource metadata. A missing scope requires additional owner authorization; it must never be bypassed. Keep tokens out of logs, URLs and source files.

## Draft safety and recovery

Only create or update a draft after an explicit user request. Keep one stable operation UUID across retries. Read `contentVersion` before editing; a conflict requires a fresh read and a new user decision. An uncertain response requires recovery with the original operation UUID, because a timeout does not prove a save failed. Review every draft in Quotae before sending.

The server is part of a controlled rollout. Availability, native approval and public ChatGPT publication are separate checks. A local test or a visible endpoint does not establish access for an arbitrary account.