Final POS – Custom POS Builder
oficialCrie 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
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
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.
| Endpoint | https://ai.finalpos.com/mcp |
| Transporte | HTTP transmissível |
| Autenticação | OAuth 2.1 com PKCE (entrar com Final), ou uma chave de conexão fai_ como Authorization: Bearer |
| Nome no registro | com.finalpos/final |
| Atua como | A pessoa que o conectou, em uma empresa, dentro dos pacotes que ela permitiu |
| Custo | Grá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
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) oufpm_(Hub) pertencem aos servidores próprios desses produtos e não são aceitas aqui. Crie uma chavefai_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.
| Pacote | Produto | O que cobre | Listado por padrão |
|---|---|---|---|
catalog | Hub | Produtos, variantes, categorias, opções, modificadores, fotos de produtos e biblioteca de mídia | ✓ |
inventory | Hub | Níveis de estoque e histórico, transferências, fornecedores, ordens de compra, regras de reposição, importação/exportação de estoque em CSV | |
orders | Hub | Pedidos, reembolsos e sincronização de pedidos de e-commerce (somente leitura: o caixa faz os pagamentos) | |
customers | Hub | Registros de clientes, notas, histórico de pedidos e importação de clientes | |
reports | Hub | Resumo financeiro, vendas e detalhamentos de pagamento, vendas por funcionário, sessões, transações, exportação de registros | |
team | Hub | Membros da equipe, funções e permissões | |
store | Hub | Lojas, estações, impostos e extensões do Hub | |
bookings | Hub | Serviços reserváveis: regras, recursos, disponibilidade, retenções e confirmações | |
build | Flow | Criar e implantar apps de PDV Final: fundamentação de API, blueprints, arquivos de fluxo, sandboxes de pré-visualização, validação, implantação | ✓ |
build_data | Flow | Tabelas 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 carregamdestructiveHint, 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_secretpede 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