> ## Documentation Index
> Fetch the complete documentation index at: https://api.aodocs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP

> Connect an MCP client to the AODocs MCP service for tool calls over Streamable HTTP, with MCP OAuth or a core API bearer token.

The AODocs MCP service exposes an MCP endpoint for tool calls and an OAuth 2.0 / OpenID Connect authorization server for MCP clients. It sits on the Document Assistant host alongside the REST AI API, under a separate mount path.

For authentication, the MCP service supports both:

* **MCP OAuth 2.0 / OpenID Connect** with easy dynamic client registration — this flow works for **Google users** (end users sign in with Google)
* **Direct bearer-token** authentication, using the **same tokens as the AODocs REST API** (see [Access APIs with Bearer tokens](/authentication/access-apis-with-bearer-tokens) and the [Authentication](/authentication) overview)

In both cases, AODocs separately verifies whether the authenticated account is authorized for the tenant in the MCP URL.

<Info>
  **MCP is not part of the OpenAPI playground.** The live Document Assistant OpenAPI documents the REST AI API (including A2A). MCP uses `/assistant/tools/mcp/v1/...` and is documented on this page from the AODocs MCP Integration Guide.
</Info>

## Base URLs and endpoints

The MCP service is mounted under `/assistant/tools/mcp/v1`.

The tenant-scoped MCP endpoint is:

```text theme={null}
/assistant/tools/mcp/v1/tenants/{tenant}/mcp
```

Example (US):

```text theme={null}
https://document-assistant.us.aodocs.app/assistant/tools/mcp/v1/tenants/example.com/mcp
```

Replace `{tenant}` with your AODocs tenant identifier (typically a domain-like string such as `example.com`). The service expects the exact tenant value configured in AODocs.

Use the same regional Document Assistant host as for the REST AI API (`document-assistant.us.aodocs.app` or `document-assistant.eu.aodocs.app`).

| Purpose | URL |
| - | - |
| MCP endpoint | `https://<host>/assistant/tools/mcp/v1/tenants/{tenant}/mcp` |
| OAuth authorization endpoint | `https://<host>/assistant/tools/mcp/v1/authorize` |
| OAuth token endpoint | `https://<host>/assistant/tools/mcp/v1/token` |
| Dynamic client registration | `https://<host>/assistant/tools/mcp/v1/register` |
| OIDC discovery | `https://<host>/.well-known/openid-configuration` |
| OAuth authorization server metadata | `https://<host>/.well-known/oauth-authorization-server` |

Clients should follow the absolute URLs returned by discovery instead of reconstructing them manually.

## Transport and protocol

This service uses **MCP over Streamable HTTP in stateless mode**:

* the MCP endpoint is a regular HTTP endpoint
* clients connect to `/assistant/tools/mcp/v1/tenants/{tenant}/mcp`
* SSE is not the configured transport for this deployment
* each MCP request is self-contained
* clients should not rely on server-side session affinity

Expected request flow:

1. `initialize`
2. `notifications/initialized`
3. `tools/list`
4. `tools/call`

Supported protocol versions: `2024-11-05`, `2025-03-26`, `2025-06-18`, `2025-11-25`. An unsupported `MCP-Protocol-Version` yields `400 Bad Request`.

Authenticated MCP requests use:

```http theme={null}
Authorization: Bearer <access-token>
```

The bearer token can be an access token from the MCP OAuth flow below, or the same kind of token you would send to the AODocs REST API — see [Access APIs with Bearer tokens](/authentication/access-apis-with-bearer-tokens).

## Authentication and discovery

| Mode | When to use |
| - | - |
| MCP OAuth 2.0 / OIDC | Your MCP client needs discovery, dynamic client registration, and refresh tokens. **Works for Google users** (Google sign-in during the OAuth flow). |
| Direct bearer token | You already have a token accepted by the AODocs REST API and want to reuse it — see [Access APIs with Bearer tokens](/authentication/access-apis-with-bearer-tokens) |

During the MCP OAuth flow, end users authenticate with Google. Required Google scopes: `openid`, `https://www.googleapis.com/auth/userinfo.email`, `https://www.googleapis.com/auth/userinfo.profile`. Dynamic client registration is the easy path for public loopback MCP clients.

The service supports authorization code flow, refresh token flow, PKCE with S256, dynamic client registration, and direct bearer-token authentication without running MCP OAuth.

Discovery documents are **host-level** (not tenant-specific):

* `https://<host>/.well-known/openid-configuration`
* `https://<host>/.well-known/oauth-authorization-server`

Discover OAuth metadata from those root well-known URLs, then follow the absolute `issuer`, `authorization_endpoint`, `token_endpoint`, and `registration_endpoint` values returned.

## OAuth flow (summary)

1. Discover authorization server metadata.
2. Dynamically register the client if needed.
3. Start an authorization-code flow with PKCE.
4. Complete Google sign-in and consent in the browser.
5. Exchange the authorization code at the token endpoint.
6. Store access and refresh tokens.
7. On each tool call, AODocs checks that the account is authorized for the tenant in the MCP URL.

### Dynamic client registration

Registration endpoint: `https://<host>/assistant/tools/mcp/v1/register`.

Dynamic registration is the expected path for public loopback clients without a prior `client_id`. Only **loopback** redirect URIs are allowed:

* `http://localhost:*`
* `http://127.0.0.1:*`

MCP clients are treated as public clients (`token_endpoint_auth_method="none"`); the proxy does not issue a usable `client_secret`.

Registration fields follow the standard OAuth client metadata model used by the MCP SDK (`redirect_uris` required; optional `grant_types`, `response_types`, `scope`, `client_name`, and related metadata fields). Defaults include `grant_types: ["authorization_code", "refresh_token"]` and `response_types: ["code"]`.

### Token response shape

```json theme={null}
{
  "access_token": "eyJhbGciOiJIU...",
  "token_type": "Bearer",
  "expires_in": 3599,
  "scope": "openid https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/userinfo.profile",
  "refresh_token": "eyJhb..."
}
```

Treat `expires_in` as authoritative. Persist the latest refresh token if rotation occurs.

## Working client sequence

**With MCP OAuth:** discover → register (if needed) → authorize with PKCE → exchange code → open MCP URL → `initialize` → `notifications/initialized` → `tools/list` → `tools/call`.

**With an existing AODocs REST API token:** open the tenant MCP URL with `Authorization: Bearer <access-token>` (same tokens as documented under [Access APIs with Bearer tokens](/authentication/access-apis-with-bearer-tokens)), then the same MCP initialize / tools flow.

## Tools

Tool availability can differ by environment. Call `tools/list`; if a tool is absent, that feature is disabled in the current deployment.

### Annotations

| Hint set | Tools |
| - | - |
| Read-only (`readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: false`) | `ask_aodocs`, `get_document_content`, `search_fulltext`, `get_document_metadata`, and when available `search_libraries`, `search_document_semantic`, `get_document_text` |
| Mutating (`readOnlyHint: false`, `destructiveHint: false`, `idempotentHint: false`, `openWorldHint: false`) | `create_document`, `create_attachment` |

### Always available

#### `ask_aodocs`

Natural-language question over documents the user can access.

| Parameter | Type | Notes |
| - | - | - |
| `query` | string, required | Question about documents in AODocs |
| `libraryIds` | string\[], optional | Limit to libraries; omit for all accessible |
| `documentIds` | string\[], optional | Limit to documents; omit for all accessible |

Returns `answer` and `sources` (document/attachment references and quotes).

```json theme={null}
{
  "name": "ask_aodocs",
  "arguments": {
    "query": "What is the retention period for invoices?",
    "libraryIds": ["library_123"]
  }
}
```

#### `get_document_content`

Download URLs for a document's attachments (`documentId` required; optional `versionId`, `attachmentIds`). Treat `downloadHeaders` as mandatory when present; URLs may be time-limited.

#### `search_fulltext`

Keyword/fulltext search (`query` required; optional `libraryIds`, `sort` with `fieldName` / `order`, `pageSize`, `pageToken`). Returns `hits`, `total`, `totalPrecision`, `nextPageToken`.

#### `get_document_metadata`

Document metadata (`documentId` required; optional `versionId`, including `draft` / `HEAD` / `LATEST` / `CURRENT` semantics as documented in the integration guide).

#### `create_document`

Create a document (`title`, `libraryId` required; optional `documentClassId`, `content` as plain text or Markdown).

#### `create_attachment`

Add a text attachment (`documentId`, `title` required without file extension; optional `content`).

### When semantic search is enabled

* **`search_libraries`** — find libraries by name or semantic description (`query` required; `*` lists all accessible; optional `limit`, `include_metadata`).
* **`search_document_semantic`** — semantic search over indexed content (`query` required; optional `documentIds`, `libraryIds`, `limit`).

### When text extraction is enabled

* **`get_document_text`** — extract text from attachments (`documentId` required; optional `versionId`, `attachmentId`).

## Permissions

All tool results are filtered by the authenticated user's permissions. Tenant access is enforced before any tool runs. Write operations may fail without the required document or library permissions.

## Errors

| Status | Typical cause |
| - | - |
| `400` | Malformed OAuth/MCP request, unsupported protocol version, invalid parameters |
| `401` | Missing/expired/invalid token, or OAuth incomplete |
| `403` | Authenticated but no access to tenant or resource |
| `404` | Unknown document, attachment, library, or wrong path |
| `429` | Rate limited — retry with backoff |
| `5xx` | Upstream or internal failure — retry idempotent reads with backoff |

OAuth exchange may also return standard errors such as `invalid_client`, `invalid_grant`, `unauthorized_client`, `invalid_request`, or `access_denied`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.