Final POS MCP

<p align="center"> <img src="assets/final-icon.png" alt="Final" width="128" /> </p>

<h1 align="center">Final POS MCP</h1>

<p align="center"> Build custom <strong>point of sale, kiosk, self-checkout, KDS & in-person payment apps</strong> with AI agents —<br /> from Gemini CLI, Claude Code, Cursor, ChatGPT, or any MCP client. </p>

<p align="center"> <a href="https://finalpos.com">finalpos.com</a> · <a href="https://build.finalpos.com">Final Builder</a> · <a href="https://docs.finalpos.com">API Docs</a> </p>

---

Final lets anyone create their own POS — every pixel, every permission, every interaction — and run it on any hardware: desktop, tablet, mobile, kiosk, payment terminal, line buster, or menu board, with integrated card payments in 24+ countries.

This repo is the official home for connecting your own AI agent to Final. It ships:

• A Gemini CLI extension (this repo installs directly).
• The hosted Final Flows MCP server — 20 tools for grounded API lookups, vetted screen blueprints, flow file writes, live sandbox previews, validation gates, and deploys.
• The Final docs MCP server — search the Final POS REST API.
• Setup snippets for Claude Code, Cursor, ChatGPT, and any MCP client.

Everything your agent builds appears live in the Final builder: the app shows up in your home grid, the agent's session appears as a chat, and every file write is a restorable checkpoint.

Get an API key

All clients authenticate with a Final organization API key (sk_...):

1. Sign in at build.finalpos.com.
2. Open a flow, then in the chat rail click the cable icon → "Connect your AI tool".
3. Mint a key — it is shown once, so copy it right away.

Install

Gemini CLI

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

You'll be prompted for your FINAL_API_KEY during install (stored in your system keychain). Change it later with:

gemini extensions config final-pos

Then start building:

/final-pos:new a coffee-shop kiosk with a product grid, cart, and card payments
/final-pos:preview   # live sandbox preview URL
/final-pos:validate  # run the full gate suite
/final-pos:deploy    # ship it

Claude Code

claude mcp add final-flows --transport http https://build.finalpos.com/api/mcp \
  --header "Authorization: Bearer sk_YOUR_KEY"

Cursor

Or add to ~/.cursor/mcp.json manually:

{
  "mcpServers": {
    "final-flows": {
      "url": "https://build.finalpos.com/api/mcp",
      "headers": { "Authorization": "Bearer sk_YOUR_KEY" }
    }
  }
}

ChatGPT and any other MCP client

The server speaks standard Streamable HTTP:

• Endpoint: https://build.finalpos.com/api/mcp
• Auth header: Authorization: Bearer sk_YOUR_KEY (or x-api-key: sk_YOUR_KEY)

In ChatGPT, add it as a connector under Settings → Connectors (developer mode). Works the same in VS Code, Windsurf, Zed, and anything else that speaks MCP.

What your agent can do

Category	Tools
Grounding	lookup_command_frame, lookup_pos_api, lookup_engine_component, list_blueprints, get_blueprint, get_scaffold
Flow lifecycle	list_flows, create_flow, connect_chat, log_message, read_flow_files, write_flow_files, delete_flow_files
Preview & ship	start_preview, sync_preview, get_preview_status, stop_preview, validate_flow, open_in_builder, deploy_flow

A typical build: get_scaffold → create_flow → ground every UI call in lookup_command_frame → adapt a vetted blueprint → write_flow_files → validate_flow → start_preview → hand you a live URL.

All tool calls are scoped to your own organization's flows. Rate limits per key: 30 preview boots/hour, 12 builds+deploys/hour, 300 file writes/hour.

Security

• Your API key is org-scoped and revocable; the secret is never stored by this extension repo — Gemini CLI keeps it in your system keychain.
• The MCP servers are hosted by Final; no code from this repo runs locally except prompt/context files.
• Agents cannot touch engine-owned files, and every deploy passes guardrail, typecheck, and secret scans.

License

Apache-2.0 © Final Commerce