Final POS – Custom POS Builder

oficial

Crie um POS personalizado com IA. Projete fluxos de checkout, quiosques de autoatendimento e aplicativos de terminal de pagamento, visualize-os ao vivo e implante em hardware real com pagamentos por cartão. Também gerencia a loja: produtos, estoque, pedidos, clientes e relatórios de vendas. Remoto, OAuth.

O que você pode fazer com Final POS – Custom POS Builder MCP?

  • Criar apps POS personalizados a partir de uma descrição — Peça ao seu assistente para criar um fluxo de checkout, como um quiosque de cafeteria, e receba um link de pré-visualização ao vivo.
  • Validar e implantar fluxos POS — Solicite a validação dos arquivos de fluxo do seu app e envie a versão mais recente para seus terminais de pagamento e quiosques.
  • Monitorar e gerenciar o inventário — Verifique os níveis de estoque, encontre itens com estoque baixo e elabore pedidos de compra para seus fornecedores habituais.
  • Analisar o desempenho de vendas — Compare as vendas por categoria entre semanas ou identifique seus principais clientes e suas compras.
  • Gerenciar catálogo e clientes — Adicione produtos a partir de uma planilha com fotos ou configure serviços reserváveis com funcionários designados.

Servidor MCP hospedado

npx add-mcp 'https://ai.finalpos.com/mcp'

Instala no Claude Code, Codex, Cursor e outros

Documentação

Final

Servidor MCP Final: crie apps de PDV personalizados com IA

Conecte Claude, ChatGPT, Gemini, Cursor, Codex ou qualquer cliente MCP ao Final:
crie apps de PDV personalizados com Flow (fluxos de checkout, quiosques de autoatendimento, terminais de pagamento)
e gerencie a loja por trás deles pelo Hub, através de um único servidor.

https://ai.finalpos.com/mcp

MCP Registry: com.finalpos/final Add to Cursor Install in VS Code License: Apache-2.0

Conectar · O que ele pode fazer · Referência de ferramentas · Perguntas frequentes · finalpos.com


O servidor MCP Final é o servidor oficial do Model Context Protocol para Final, a plataforma de comércio para pontos de venda personalizados. Um único endpoint remoto, https://ai.finalpos.com/mcp, dá a um agente de IA acesso a todos os produtos Final que o comerciante permitir:

  • Flow, o construtor de apps de PDV personalizados: descreva um checkout e o agente o constrói a partir de blueprints de tela validados, com base nas APIs de PDV com versão fixa da Final, depois o valida, retorna um link de pré-visualização ao vivo e o implanta em terminais de pagamento, tablets e quiosques. PDV de balcão, autoatendimento, pedidos em restaurantes, displays de cozinha e apps de pagamento presencial.
  • Hub, o back office por trás desses apps: produtos e catálogo, estoque e ordens de compra, pedidos, clientes, relatórios de vendas, equipe e funções, lojas, impostos, reservas.

Você entra com sua conta Final (OAuth 2.1) e escolhe a empresa e o que o agente pode fazer. Não há nada para instalar ou executar localmente.

Endpointhttps://ai.finalpos.com/mcp
TransporteHTTP transmissível
AutenticaçãoOAuth 2.1 com PKCE (entrar com Final), ou uma chave de conexão fai_ como Authorization: Bearer
Nome no registrocom.finalpos/final
Atua comoA pessoa que o conectou, em uma empresa, dentro dos pacotes que ela permitiu
CustoGrátis para conectar; o que o agente faz segue seu plano Final, como se você fizesse na Final

Conectar

A maioria dos clientes só precisa da URL. Eles abrem uma página de login da Final onde você escolhe a empresa e os pacotes, e então estão conectados.

Claude (claude.ai, Claude Desktop)

Configurações → Conectores → Adicionar conector personalizado, URL https://ai.finalpos.com/mcp.

ChatGPT

Configurações → Apps e Conectores → Configurações avançadas → Modo desenvolvedor, depois Criar com a URL https://ai.finalpos.com/mcp.

Claude Code

claude mcp add --transport http final https://ai.finalpos.com/mcp

Execute /mcp no Claude Code e escolha Autenticar. Ou instale o plugin, que adiciona o servidor junto com a habilidade do playbook Final. Dentro do Claude Code:

/plugin marketplace add Final-Commerce/final-pos-mcp
/plugin install final@final

Gemini CLI

gemini extensions install https://github.com/Final-Commerce/final-pos-mcp

A extensão adiciona o servidor, o playbook Final e comandos: /final-pos:stock, /final-pos:sales, /final-pos:new, /final-pos:preview, /final-pos:validate e /final-pos:deploy. Entre uma vez com /mcp auth final dentro do Gemini CLI. Para adicionar apenas o servidor:

gemini mcp add --transport http final https://ai.finalpos.com/mcp

Cursor

Add to Cursor

Ou em ~/.cursor/mcp.json:

{
  "mcpServers": {
    "final": { "url": "https://ai.finalpos.com/mcp" }
  }
}

VS Code (GitHub Copilot)

Instalar no VS Code, ou:

code --add-mcp '{"name":"final","type":"http","url":"https://ai.finalpos.com/mcp"}'

Codex, scripts e clientes sem OAuth

Crie uma chave de conexão em ai.finalpos.com/connections. Ela é mostrada uma única vez, e a página imprime o trecho exato para cada cliente. Para Codex, adicione isto a ~/.codex/config.toml:

[mcp_servers.final]
url = "https://ai.finalpos.com/mcp"
http_headers = { "Authorization" = "Bearer fai_YOUR_KEY" }

Qualquer outro cliente: POST https://ai.finalpos.com/mcp com Authorization: Bearer fai_YOUR_KEY.

Chaves que começam com sk_ (Flow) ou fpm_ (Hub) pertencem aos servidores próprios desses produtos e não são aceitas aqui. Crie uma chave fai_ em vez disso, ou use OAuth.

Verifique se funciona

Pergunte ao seu agente: "Use a Final para me dizer a qual empresa você está conectado e quais pacotes você pode usar." Ele chama get_connection e list_packs.

O que seu agente pode fazer

As ferramentas são agrupadas em pacotes. Ao conectar, você escolhe quais pacotes o agente pode usar, e esses também são os escopos do OAuth. Para manter o contexto do modelo pequeno, uma conexão lista apenas alguns pacotes por vez. As ferramentas principais alcançam o resto: find_tools pesquisa em todos os pacotes permitidos, e call_tool chama qualquer ferramenta permitida pelo nome.

PacoteProdutoO que cobreListado por padrão
catalogHubProdutos, variantes, categorias, opções, modificadores, fotos de produtos e biblioteca de mídia✓
inventoryHubNíveis de estoque e histórico, transferências, fornecedores, ordens de compra, regras de reposição, importação/exportação de estoque em CSV
ordersHubPedidos, reembolsos e sincronização de pedidos de e-commerce (somente leitura: o caixa faz os pagamentos)
customersHubRegistros de clientes, notas, histórico de pedidos e importação de clientes
reportsHubResumo financeiro, vendas e detalhamentos de pagamento, vendas por funcionário, sessões, transações, exportação de registros
teamHubMembros da equipe, funções e permissões
storeHubLojas, estações, impostos e extensões do Hub
bookingsHubServiços reserváveis: regras, recursos, disponibilidade, retenções e confirmações
buildFlowCriar e implantar apps de PDV Final: fundamentação de API, blueprints, arquivos de fluxo, sandboxes de pré-visualização, validação, implantação✓
build_dataFlowTabelas personalizadas (o banco de dados do app), o cofre de segredos e extensões do Flow

Os nomes das ferramentas carregam seu produto: hub_get_products, hub_find_low_stock, flow_create_flow, flow_deploy_flow. TOOLS.md lista cada ferramenta, com seu pacote, se altera dados e seus argumentos.

Ferramentas principais (sempre listadas): get_connection, list_packs, find_tools, call_tool, enable_packs, disable_packs, switch_company.

Coisas para pedir

Criando apps de PDV personalizados (Flow)

  • "Crie um quiosque de cafeteria com grade de produtos, modificadores, carrinho e pagamentos com cartão, e me dê um link de pré-visualização."
  • "Adicione uma tela de gorjeta ao meu app de balcão e valide-o."
  • "Crie um fluxo de autoatendimento para uma pequena mercearia com leitura de código de barras e tela de recibo."
  • "Envie a versão mais recente do meu fluxo de autoatendimento."

Uma criação de app geralmente executa flow_get_scaffold → flow_create_flow → flow_lookup_command_frame (fundamentação) → flow_get_blueprint → flow_write_flow_files → flow_validate_flow → flow_start_preview, e retorna uma URL de pré-visualização ao vivo. Tudo o que o agente cria também aparece no construtor Final, onde cada gravação de arquivo é um checkpoint restaurável.

Gerenciando a loja (Hub)

  • "Quais produtos estão abaixo do ponto de reposição na loja da Rua Principal? Elabore uma ordem de compra para o fornecedor habitual."
  • "Compare as vendas da semana passada por categoria com a semana anterior."
  • "Adicione estes 40 produtos da planilha anexada, com fotos."
  • "Quem foram meus dez principais clientes este mês, e o que eles compraram?"
  • "Configure uma massagem de 45 minutos como serviço reservável com dois terapeutas."

Segurança e permissões

  • Sua função ainda se aplica. Cada chamada do Hub é executada como a pessoa que conectou, e o Hub verifica a função ao vivo dela em cada chamada. Ações exclusivas de proprietário continuam exclusivas de proprietário.
  • Os pacotes são a permissão. O agente só pode chamar ferramentas nos pacotes que você permitiu. Você pode alterar pacotes ou desconectar a qualquer momento em ai.finalpos.com/connections, e desconectar revoga todos os tokens de uma vez.
  • Gravações são rotuladas. Ferramentas de leitura carregam readOnlyHint, e implantações e exclusões carregam destructiveHint, para que os clientes possam perguntar antes de agir. O servidor diz aos agentes para confirmarem implantações, exclusões e alterações em massa com você.
  • O dinheiro fica no caixa. Receber pagamentos, reembolsar e anular pedidos não estão disponíveis via MCP.
  • Segredos nunca passam pelo modelo. flow_request_secret pede que você insira uma chave de API no construtor.
  • Tudo é registrado. A página de Conexões mostra cada cliente conectado e cada chamada que ele fez, ao vivo.
  • Limites do Flow: O Flow permite 30 inicializações de pré-visualização, 12 criações e implantações, e 300 gravações de arquivo por hora.

Privacidade e suporte

  • O que a Final mantém. A conexão (quem a fez, a empresa e os pacotes), o token que ela usa para acessar Hub e Flow (criptografado) e um log de cada chamada de ferramenta: a ferramenta, o resultado, quanto tempo levou e pré-visualizações editadas dos argumentos e do resultado. Você vê esse log na página de Conexões.
  • O que a Final não vê. Sua conversa. Clientes MCP enviam chamadas de ferramentas, não o chat ao redor delas.
  • Desconectar exclui o token armazenado e revoga todos os tokens emitidos para essa conexão.
  • Política de privacidade · Termos
  • Suporte: support@finalpos.com. Para problemas com este guia ou o plugin, abra uma issue.

Endpoint direto do Flow

Configurações feitas antes do gateway ainda podem usar https://flow.finalpos.com/api/mcp com uma chave sk_ do Flow (nome no registro com.finalpos.build/final-flows). Ele continua funcionando, mas novas configurações devem usar https://ai.finalpos.com/mcp, que inclui o Flow.

Perguntas frequentes

O que é o servidor MCP Final?

É o servidor MCP oficial para Final POS. Uma única URL remota, https://ai.finalpos.com/mcp, permite que um assistente de IA leia e gerencie o back office Final de um comerciante (Hub) e crie apps de ponto de venda (Flow).

O ChatGPT ou o Claude podem gerenciar meu inventário do Final POS?

Sim. Permita o pacote inventory ao conectar. O agente pode verificar níveis de estoque, encontrar estoque baixo, sugerir reposições, emitir ordens de compra e registrar mercadorias recebidas.

Um agente de IA pode criar um app de PDV na Final?

Sim. Com o pacote build, o agente cria um fluxo, escreve o app usando as APIs com versão fixa da Final e blueprints de tela validados, valida-o e retorna uma URL de pré-visualização ao vivo. Você o lança pelo construtor Final.

Preciso de uma chave de API?

Não, se seu cliente suportar OAuth (Claude, ChatGPT, Claude Code, Cursor, Gemini CLI, VS Code): basta entrar com a Final. Codex e scripts usam uma chave fai_ de ai.finalpos.com/connections.

Em qual empresa ele atua?

Na que você escolher ao conectar. Se sua conta tiver várias, o agente pode chamar switch_company.

O agente pode receber pagamentos ou emitir reembolsos?

Não. Pagamentos, reembolsos e anulações acontecem no caixa. Pedidos são somente leitura via MCP.

Por que meu agente só vê algumas ferramentas?

Os clientes colocam cada ferramenta listada no contexto do modelo, e a qualidade cai com listas longas. O agente encontra o resto com find_tools, chama-as com call_tool, ou lista um pacote inteiro com enable_packs.

Há algum custo?

Conectar é grátis. O que o agente faz é cobrado como o mesmo trabalho feito na Final por você, sob seu plano Final.

Onde estão os documentos da API do Final POS?

Em finalpos.com/docs. Um agente criando um app não precisa deles separadamente: o pacote build fundamenta cada chamada contra as APIs com versão fixa da Final (flow_lookup_pos_api, flow_lookup_command_frame).

Sobre este repositório

Este repositório contém o guia de configuração público, as entradas do Registro MCP (server.json, legacy/), a extensão do Gemini CLI (gemini-extension.json, GEMINI.md, commands/), os marketplaces de plugins do Claude Code e Cursor (.claude-plugin/, .cursor-plugin/, e plugins/final/, que ambos compartilham) e a referência de ferramentas gerada com seu gêmeo legível por máquina catalog.json, que o cartão do servidor em https://ai.finalpos.com/.well-known/mcp/server-card.json também lê. GEMINI.md e a habilidade do Claude são o mesmo playbook, e o CI verifica se eles correspondem. O servidor em si é hospedado pela Final; nenhum código deste repositório é executado na sua máquina.

Licença

Apache-2.0 © Final Commerce