# AUVY for developers and agents

AUVY keeps a team's projects current from their mail, meetings and files. Everything the product does goes through one public API at `https://api.auvy.ai`, and an MCP server on the same host lets assistants such as Claude, ChatGPT, Cursor and Codex work in a person's projects as that person.

AUVY is in private beta: an account comes through [request access](https://www.auvy.ai/access), a walkthrough or an invitation.

## MCP server

- URL: `https://api.auvy.ai/mcp` (streamable HTTP; protocol 2025-11-25, 2025-06-18)
- Server card: https://www.auvy.ai/.well-known/mcp/server-card.json
- Sign-in: OAuth 2.1 with PKCE, see [auth.md](https://www.auvy.ai/auth.md)
- Tools: `get_profile`, `list_projects`, `open_project`, `search_project`, `list_files`, `read_file`, `write_file`, `edit_file`, `move_file`, `trash_file`, `file_versions`, `list_senses`, `run_sense`, `run_sense_write`, `integration_guide`, `open_auvy`, `mention_search`
- Hints: reads are marked read only; `trash_file` and `run_sense_write` are marked destructive so clients ask the person first; saves and edits keep every version.

Connect from Claude Code:

```bash
claude mcp add --transport http auvy https://api.auvy.ai/mcp
```

## API

- Contract: [https://api.auvy.ai/openapi.json](https://api.auvy.ai/openapi.json) (OpenAPI 3.1, every operation with an `operationId`; `x-auvy-state` says whether it is open, on preview or planned)
- Catalog: https://api.auvy.ai/.well-known/api-catalog and [this site's](https://www.auvy.ai/.well-known/api-catalog)
- Health: `GET https://api.auvy.ai/health`
- Families: agents and runs, bots, chats, files, meetings, senses, decisions, and inference in the OpenAI and Anthropic wire formats (`/v1/responses`, `/v1/chat/completions`, `/v1/messages`, `/v1/embeddings`, `/v1/models`)
- Scope: `X-Workspace-Id` and `X-Brain-Id` headers say which workspace and project a call acts in

### Conventions

- One error body on every failure: `{"error":{"code":"NOT_FOUND","message":"…","status":404,"retryable":false,"request_id":"req_…"}}`
- Every answer carries `x-request-id`; quotas are announced in `RateLimit` and `RateLimit-Policy` headers; 429 and 503 carry `retry-after`
- A POST that creates accepts `Idempotency-Key`
- Typed lists answer `{ "object": "list", "data": [], "has_more": false, "next": null }` and page with `limit` and `after`
- Runs and model output stream as server-sent events
- Versioned by path (`/v1`); changes inside `/v1` only add

## Credentials

| Credential | For | Acts as |
| --- | --- | --- |
| OAuth access token (scope `auvy.access`) | MCP clients: Claude, ChatGPT, Claude Code | The person who signed in |
| Personal key `auk_p_…` | Cursor, Codex, scripts | The person who created it |
| Workspace key `ak_live_…` | Automation | The workspace, or one project when bound to it |

Keys are created by a signed-in member in AUVY under Developers, Keys (https://www.auvy.ai/os/developers/keys).

## More

- [auth.md](https://www.auvy.ai/auth.md): how an agent signs in, step by step
- [llms.txt](https://www.auvy.ai/llms.txt): what AUVY is, for assistants
- [Trust center](https://trust.auvy.ai): data handling, subprocessors, DPA
- Security reports: security@auvy.ai