MCP server (Claude & AI assistants)

It is a secure bridge between your cellar data and an MCP-capable client. After you authenticate, the assistant can call VinoCellar tools on your behalf, subject to your subscription and account rules.

The exact public URL is shown in the VinoCellar app on the MCP / access tokens screen (in-app route /app/mcp), under “MCP server address”. Copy it exactly—do not guess from an old screenshot.

On the public VinoCellar production app, the default MCP host is https://mcp.vinocellar.app . Always prefer the value displayed in the app if it differs (custom builds or future configuration via EXPO_PUBLIC_MCP_SERVER_URL).

1. Open the app → MCP (or Settings → VinoCellar MCP → manage tokens).
2. Copy the server URL from the dedicated block.
3. In Claude Desktop (or another client), add an MCP server and paste that URL per the client’s current documentation.
4. Complete the OAuth / browser step when the client connects; you will paste the personal token from the app when prompted.

The VinoCellar MCP server follows the MCP specification using Streamable HTTP: your client talks to the MCP endpoint over HTTPS (not a generic “REST catalogue” you browse by hand).

On first connect, the MCP client starts an OAuth-style flow. A browser window asks you to paste the personal access token you created in the VinoCellar app; the MCP server validates it with the VinoCellar API, then issues credentials your client sends as a Bearer token on later MCP requests.

Tokens created from the MCP screen are created with scopes mcp:read and mcp:write so the assistant can use the tools VinoCellar registers for MCP.

For a quick health check that the host is reachable (not a full MCP session), the server responds to GET /ping with plain text pong.

Tokens identify your account to the MCP server during setup:

1. In the app, open the MCP screen and tap create token.
2. Give it a clear label (e.g. “MacBook”, « Claude Desktop », “Cursor”).
3. Copy the token value immediately—it is shown only once.
4. Revoke a token from the same screen if a device is lost or you want to disconnect a client.

Treat tokens like passwords. Anyone with the token and the server URL could access your cellar through MCP until you revoke it.

These are the tool names exposed to MCP clients (exact identifiers):

• vinocellar_whoami — verify the linked account; the JSON response includes an mcp object (welcome text, FAQ URL, tool hints).
• vinocellar_help — return the same onboarding JSON as the mcp block from vinocellar_whoami without calling the profile API again.
• vinocellar_list_wines — broad inventory list; prefer vinocellar_search_wines when filtering by name or domain.
• vinocellar_search_wines — text search across your bottles.
• vinocellar_get_caves — list cellars before targeting one.
• vinocellar_get_cave — cellar layout with bins; provides log_id values for vinocellar_move_bottle.
• vinocellar_move_bottle — move a bottle to another bin or cellar using log_id from vinocellar_get_cave.
• vinocellar_import_wine — add a wine from structured wine_data (GeminiWineResponse shape) and optional front/back label images in base64; requires an active MCP subscription on the account.

MCP tools are limited to cellar inventory operations as listed above.

The in-app Vino chat assistant, food-and-wine pairing wizard, tasting journal, and similar product features are not exposed as separate MCP tools—use the mobile or web app for those experiences.

VinoCellar targets people who use a compatible MCP assistant (Claude Desktop, Cursor, etc.): you copy the server URL from the app and create a personal token.

There is no separate third-party OAuth application or OpenAPI document for “MCP as REST”: the integration contract is the MCP protocol (tools/list and each tool’s schema/description as your client shows them).

Credits (tokens) are mainly spent on in-app AI label scans. The optional MCP subscription is separate: while it is active, calls through the MCP server for supported operations are not limited by your scan-credit balance in the same way.

Claude Desktop and other clients that support MCP with VinoCellar’s transport are supported today. ChatGPT and Gemini compatibility is planned; check release notes and this FAQ for updates.