Servidor MCP (Claude e assistentes de IA)

É uma ponte segura entre os dados da adega e um cliente compatível com MCP. Após autenticação, o assistente pode invocar ferramentas VinoCellar em seu nome, conforme a subscrição e as regras da conta.

O URL público exato aparece na app VinoCellar, ecrã MCP / tokens (rota interna /app/mcp), bloco «Endereço do servidor MCP». Copie-o tal como está.

Na app pública de produção VinoCellar, o anfitrião MCP predefinido é https://mcp.vinocellar.app . Prefira sempre o valor mostrado na app se for diferente (builds personalizados ou configuração futura via EXPO_PUBLIC_MCP_SERVER_URL).

1. Abra a app → secção MCP (ou Definições → VinoCellar MCP → gerir tokens).
2. Copie o URL do servidor no bloco indicado.
3. No Claude Desktop (ou outro cliente), adicione um servidor MCP e cole o URL segundo a documentação atual do cliente.
4. Na primeira ligação, conclua o passo OAuth no navegador; cole o token pessoal criado na app quando o formulário pedir.

O servidor MCP VinoCellar segue a especificação MCP com transporte Streamable HTTP: o seu cliente fala com o ponto de entrada MCP em HTTPS (não é um catálogo REST genérico para explorar manualmente).

Na primeira ligação, o cliente MCP inicia um fluxo tipo OAuth. No navegador cola o token de acesso pessoal criado na app VinoCellar; o servidor MCP valida-o junto da API VinoCellar e em seguida emite credenciais que o cliente envia como token Bearer nos pedidos MCP seguintes.

Os tokens criados no ecrã MCP são emitidos com os âmbitos mcp:read e mcp:write para o assistente poder invocar as ferramentas registadas pela VinoCellar.

Para verificar rapidamente que o anfitrião responde (sem sessão MCP completa), o servidor responde a GET /ping com o texto simples pong.

O token identifica a sua conta perante o servidor MCP:

1. Na app, abra o ecrã MCP e crie um token.
2. Dê-lhe um nome claro (ex. «MacBook», « Claude Desktop », «Cursor»).
3. Copie o valor de imediato — só é mostrado uma vez.
4. Revogue um token no mesmo ecrã se perder um dispositivo ou quiser desligar um cliente.

Trate os tokens como palavras-passe: quem tiver o token e o URL pode aceder à adega via MCP até revogar.

Estes são os identificadores exatos das ferramentas expostas aos clientes MCP:

• vinocellar_whoami — verificar a ligação; a resposta JSON inclui um objeto mcp (texto de boas-vindas, URL da FAQ, dicas de ferramentas).
• vinocellar_help — devolve o mesmo JSON de boas-vindas que o objeto mcp de vinocellar_whoami sem voltar a chamar a API de perfil.
• vinocellar_list_wines — inventário amplo; prefira vinocellar_search_wines para filtrar por nome ou domínio.
• vinocellar_search_wines — pesquisa de texto nas suas garrafas.
• vinocellar_get_caves — listar adegas antes de escolher uma.
• vinocellar_get_cave — disposição por casas; fornece log_id para vinocellar_move_bottle.
• vinocellar_move_bottle — mover uma garrafa para outra casa ou adega usando o log_id devolvido por vinocellar_get_cave.
• vinocellar_import_wine — adicionar um vinho a partir de wine_data estruturado (formato GeminiWineResponse) e imagens opcionais de rótulo frente/verso em base64; requer subscrição MCP ativa na conta.

As ferramentas MCP limitam-se às operações de inventário e adega indicadas acima.

O assistente Vino na app, o assistente de harmonizações, o diário de provas e outras funções de IA não são expostos como ferramentas MCP separadas — use a app móvel ou a web para esses casos.

A VinoCellar dirige-se a quem usa um cliente MCP compatível (ex.: Claude Desktop): copia o URL do servidor na app e cria um token pessoal.

Não existe uma aplicação OAuth de parceiros separada nem documentação OpenAPI «MCP como REST»: o contrato é o protocolo MCP (tools/list e a descrição/esquema de cada ferramenta tal como o cliente as mostra).

Os créditos servem sobretudo para digitalizações de rótulo na app. A subscrição MCP é separada: enquanto estiver ativa, as chamadas ao servidor MCP para operações suportadas não ficam limitadas pelo saldo de créditos de digitalização da mesma forma.

Hoje Claude Desktop e clientes MCP-compatíveis com o transporte VinoCellar. Compatibilidade ChatGPT e Gemini prevista; consulte as notas de versão e esta FAQ.