MCP - AO Docs Documentation

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 and the Authentication overview)

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

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.

Base URLs and endpoints

The MCP service is mounted under /assistant/tools/mcp/v1. The tenant-scoped MCP endpoint is:

/assistant/tools/mcp/v1/tenants/{tenant}/mcp

Example (US):

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:

initialize
notifications/initialized
tools/list
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:

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 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

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)

Discover authorization server metadata.
Dynamically register the client if needed.
Start an authorization-code flow with PKCE.
Complete Google sign-in and consent in the browser.
Exchange the authorization code at the token endpoint.
Store access and refresh tokens.
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

{
  "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), 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).

{
  "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.

​Base URLs and endpoints

​Transport and protocol

​Authentication and discovery

​OAuth flow (summary)

​Dynamic client registration

​Token response shape

​Working client sequence

​Tools

​Annotations

​Always available

​ask_aodocs

​get_document_content

​search_fulltext

​get_document_metadata

​create_document

​create_attachment

​When semantic search is enabled

​When text extraction is enabled

​Permissions

​Errors

Base URLs and endpoints

Transport and protocol

Authentication and discovery

OAuth flow (summary)

Dynamic client registration

Token response shape

Working client sequence

Tools

Annotations

Always available

`ask_aodocs`

`get_document_content`

`search_fulltext`

`get_document_metadata`

`create_document`

`create_attachment`

When semantic search is enabled

When text extraction is enabled

Permissions

Errors