# MCP overview

Exayard exposes the Model Context Protocol at `https://api.exayard.com/mcp`. It uses the Streamable HTTP transport and is protected by OAuth. Most REST API operations are also tools, named by their `operationId` in the [API reference](https://developers.exayard.com/api-reference). A few are REST only, such as sending a test webhook, resending a delivery and the webhook listener. The protocol version is [MCP 2025-06-18](https://modelcontextprotocol.io/specification/2025-06-18).

## Capabilities

Advertised at [/.well-known/mcp.json](https://api.exayard.com/.well-known/mcp.json):

- `tools`: one per REST operation that is open to MCP (projects, files, pages, assessments, products, vendors, labor, quotes, estimates, bids, webhooks and more), plus tools only agents get, such as sheet reads and document composition.
- `prompts`: [four playbooks](https://developers.exayard.com/mcp/prompts.md) for common workflows with several steps.
- `resources` and `sampling`: not built yet.

## Auth

Three bearer-token paths:

- **API key**: the same `exa_live_...` key you use on the REST API. A key belongs to an app, so `tools/list` shows only the tools its scopes reach. A key set to work in **This company** acts in its own company without naming it. A key set to work in every company that installed its app names one with the `Exayard-Organization-Id` header or an `organizationId` argument. Older `ak_` keys still work. See [Apps and keys](https://developers.exayard.com/apps-and-keys.md).
- **OAuth**: discover the authorization server at [/.well-known/oauth-protected-resource](https://api.exayard.com/.well-known/oauth-protected-resource). Clients that register through DCR get their own `client_id`. See [Dynamic Client Registration](https://developers.exayard.com/mcp/dcr.md).
- **Registered app**: a person's OAuth token from an app registered in Exayard. Name the company with the `Exayard-Organization-Id` header or an `organizationId` argument. `tools/list` shows only the tools the company's install grants. With no company named, it shows the tools the app's scopes cover. See [Scopes](https://developers.exayard.com/concepts/scopes.md) and [Authentication](https://developers.exayard.com/authentication.md#let-other-companies-install-your-app).

401 responses carry `WWW-Authenticate: Bearer realm="Exayard MCP", resource_metadata="..."` so MCP clients can negotiate without hard-coded config.

## Tool annotations

Every tool declares `readOnlyHint`, `destructiveHint`, and `idempotentHint`. Clients use these to decide auto-approval policy. Prefixes map to the intent:

| Prefix         | readOnly | destructive | idempotent |
|----------------|----------|-------------|------------|
| `get_`/`list_`/`search_`/`find_` | ✓ | ✗ | ✓ |
| `update_`/`set_`/`patch_`/`rename_`/`move_` | ✗ | ✗ | ✓ |
| `archive_`/`remove_`/`cancel_` | ✗ | ✓ | ✓ |
| `create_`/`add_`/`batch_`/`run_` | ✗ | ✗ | ✗ |

## Token budget

Tool responses larger than 60,000 characters are auto-truncated. The response carries `_truncated: true` and a `_hint` string explaining how to paginate.

## Structured content

Tools return both `content` (text fallback) and `structuredContent` (JSON object, per MCP 2025-06-18). Agents branch on `structuredContent` fields directly.