Connect an AI client with MCP
Let an AI assistant work with your data under scoped access.
Use the database connector's URL
Aviato exposes Streamable HTTP MCP at:
https://connector.example.com/mcpUse your database connector's public URL, not the dashboard or control-plane URL. Your MCP client must be able to reach it over HTTPS and support the advertised OAuth flow. Before MCP clients can obtain tokens for a self-hosted connector, Aviato checks that the connector serves its public URL: Aviato calls <public URL>/.well-known/aviato-connector, and the connector answers using its credential. Aviato must therefore reach that URL too, and the connector must run 0.3.1 or later. Older connectors keep a resource that is already registered but cannot register a new URL. Connect to a standard environment, or to your own development environment, which serves only you: the connectors of preview environments refuse MCP clients. A development environment's connector runs on your computer, so start it with aviato dev --tunnel to give it a public HTTPS address; it prints the MCP URL to use, which changes on every run.
Authorize the connection
Add the endpoint in your client's remote MCP settings and complete the sign-in and consent flow. Start with aviato:read. Request aviato:write only when the client needs to change records or execute actions.
An OAuth scope does not override the connecting user's permissions. A read-only connection stays read-only even if that user can edit records in the dashboard.
Do not paste the deployment connector token into an MCP client. It is intended for connector-to-control-plane communication.
Try a read first
Ask the client to list available collections, inspect one collection, and fetch a specific record. Results are restricted to the fields and rows the connecting user may read.
Tools include collection discovery, record listing and retrieval, and action discovery. Write tools require both the appropriate scope and role. Actions can be held by approval rules.
Pagination and file results
Record lists skip exact counts by default and return total: null with hasMore. Set count: true on list_records when an exact total is needed; counting large filtered datasets can be expensive.
Actions producing files return a resource_link instead of embedding the file in the model's context. Download it within five minutes with the same OAuth bearer token. The download is available once and belongs to the user who ran the action. Do not rerun an action to retrieve its output: the action may have already changed data.
Understand the data boundary
Record values returned to the MCP client may be sent to that client's model provider. Choose the client and provider according to your organization's requirements. Read data flow for Aviato's own AI features, which are a separate flow.
Debug a refused connection
Check HTTPS reachability, the connector's public URL, workspace membership, and the scopes you granted. If the control-plane logs say the connector did not prove it serves its URL, make sure Aviato reaches AVIATO_PUBLIC_URL and that the URL leads to this environment's connector. Aviato retries the check every ten minutes. OAuth metadata is exposed at /.well-known/oauth-protected-resource/mcp. A client without compatible remote OAuth support may not complete the connection.