# The Final MCP server > Updated: 2026-10-17 · version 2.0.0 > Canonical: https://finalpos.com/mcp The Final MCP server is the official Model Context Protocol server for Final POS. One remote URL, https://ai.finalpos.com/mcp, lets Claude, ChatGPT, Cursor, VS Code, Gemini CLI, Codex or any MCP client run a merchant's store in Hub — catalog, stock, purchase orders, orders, customers, reports, team, outlets and bookings — and build, preview and deploy point-of-sale apps with Flow. You sign in with your Final account, choose the company and what the agent may do, and there is nothing to install. It used to be two things: an app-building server for Flow, and the back office you ran by hand. Now it is one server for the whole of Final. The agent works as the person who connected it, on one company, within the packs they allowed, and every call shows up live on your Connections page. ## Server facts - **Endpoint:** https://ai.finalpos.com/mcp - **Transport:** Streamable HTTP - **Auth:** OAuth 2.1 with PKCE (sign in with Final), or a fai_ connection key as Authorization: Bearer - **Acts as:** The person who connected it, on one company, within the packs they allowed - **Tools:** 177 in 10 packs: 132 Hub, 36 Flow, 9 core - **Discovery:** tools/list and the server card are public; every tool call needs sign-in - **Registry:** com.finalpos/final (version 2.0.0) ## One server for the whole store Final's AI tools used to be split: an MCP server that only built apps, and a back office your agent couldn't reach. The Final MCP server brings them together behind one sign-in. - **Hub, the back office.** Products and photos, stock and purchase orders, orders and refunds, customers, sales reports, team and roles, outlets and taxes, and bookings. Hub checks the connecting user's role on every call, so owner-only actions stay owner-only. - **Flow, the app builder.** Create custom POS, kiosk, self-checkout and payment-terminal apps from vetted blueprints, ground every call in Final's version-locked APIs, validate with the builder's own gates, preview on a live HTTPS link and deploy. - **Finai, Final's own agent.** Hand a whole job to Finai with ask_finai and get the finished answer back. It runs as you, with the same packs, and uses Final's tools itself. ## How to connect your AI agent to Final Most clients only need the URL. The whole setup takes about a minute. 1. **Add the server.** Add https://ai.finalpos.com/mcp to your AI tool as a remote MCP server: a custom connector in Claude, an app in ChatGPT's developer mode, or one command in Claude Code, Cursor, VS Code or Gemini CLI. 2. **Sign in with Final.** Your client opens a Final sign-in page. Pick the company and the packs the agent may use, then allow it. Clients without OAuth use a fai_ connection key from ai.finalpos.com/connections instead. 3. **Check the connection.** Ask your agent: "Use Final to tell me which company you're connected to and which packs you can use." It answers with get_connection and list_packs. 4. **Give it real work.** Ask for low stock and a draft purchase order, a sales comparison, a bulk product import, or a new kiosk app with a preview link. Writes are confirmed with you first. Setup guide for every client: https://github.com/Final-Commerce/final-pos-mcp ## Configuration for each client Clients with OAuth only need the URL. Codex, scripts and clients without OAuth use a fai_ connection key from ai.finalpos.com/connections; it is shown once, so treat it like a password. ### Claude (claude.ai, Claude Desktop) ```text Settings → Connectors → Add custom connector URL: https://ai.finalpos.com/mcp ``` ### ChatGPT ```text Settings → Apps & Connectors → Advanced settings → Developer mode → Create URL: https://ai.finalpos.com/mcp ``` ### Claude Code ```bash claude mcp add --transport http final https://ai.finalpos.com/mcp ``` Then run /mcp and choose Authenticate. Or install the plugin, which adds the server and the Final playbook: /plugin marketplace add Final-Commerce/final-pos-mcp, then /plugin install final@final. ### Cursor ```json { "mcpServers": { "final": { "url": "https://ai.finalpos.com/mcp" } } } ``` Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project), or use the Add to Cursor link in the setup guide. ### VS Code (GitHub Copilot) ```bash code --add-mcp '{"name":"final","type":"http","url":"https://ai.finalpos.com/mcp"}' ``` ### Gemini CLI ```bash gemini extensions install https://github.com/Final-Commerce/final-pos-mcp ``` Adds the server, the Final playbook and /final-pos commands. Sign in once with /mcp auth final. ### Codex ```toml [mcp_servers.final] url = "https://ai.finalpos.com/mcp" http_headers = { "Authorization" = "Bearer fai_YOUR_KEY" } ``` Add to ~/.codex/config.toml with a key from ai.finalpos.com/connections. ### Any other MCP client ```text Remote MCP server (Streamable HTTP): https://ai.finalpos.com/mcp OAuth 2.1 discovery: https://ai.finalpos.com/.well-known/oauth-protected-resource/mcp ``` Or send Authorization: Bearer fai_… with a connection key. Don't add an Authorization header when using OAuth: a configured header stops the sign-in flow. ## Ask Finai: hand over a whole job Some jobs are easier to describe than to orchestrate one tool at a time. ask_finai hands a task in plain words to Finai, Final's own AI agent. Finai runs as the connection's user on its company, within the same packs, uses Final's tools itself — looking records up, creating products, building or deploying an app — and returns the finished answer. Pass the conversationId it returns to continue the thread. > Ask Finai to set up a 45-minute massage as a bookable service with two therapists, open 9 to 5 on weekdays, and tell me what it created. ## Tools and packs 177 tools, grouped in 10 packs. Packs are also what you allow when you connect. To keep the model's context small a connection lists only a few packs; find_tools searches every allowed pack, call_tool runs any allowed read-only tool and call_write_tool runs any allowed tool that changes data. Every tool has a title and explicit readOnlyHint, destructiveHint and openWorldHint annotations, so clients know which calls to confirm. ### The packs | Pack | Product | Tools | What it covers | |---|---|---:|---| | `catalog` (listed by default) | Hub | 29 | Products, variants, categories, options, modifiers, product photos and the media library | | `inventory` | Hub | 34 | Stock levels and history, transfers, suppliers, purchase orders, reorder rules, stock CSV import and export | | `orders` | Hub | 6 | Orders, refunds and e-commerce order sync (read-only: the till takes payments) | | `customers` | Hub | 8 | Customer records, notes, order history and customer import | | `reports` | Hub | 9 | Financial summary, sales and payment breakdowns, employee sales, sessions, transactions, record export | | `team` | Hub | 10 | Team members, roles and permissions | | `store` | Hub | 25 | Outlets, stations, taxes and Hub extensions | | `bookings` | Hub | 11 | Bookable services: rules, resources, availability, holds and confirmations | | `build` (listed by default) | Flow | 27 | API grounding, blueprints, flow files, preview sandboxes, validation and deploy | | `build_data` | Flow | 9 | Custom tables (the app database), the secrets vault and Flow extensions | ### Examples from each pack #### Core (always listed) How the agent learns about its connection, reaches every allowed tool and hands work to Finai. - `get_connection`: Who the connection acts as, the company, and the allowed and listed packs. - `list_packs`: Every pack with its product, tool count and whether it's allowed and listed. - `find_tools`: Search every allowed pack by what you want to do; says which dispatcher runs each match. - `call_tool`: Run any allowed read-only tool by name, listed or not. - `call_write_tool`: Run any allowed tool that creates, changes, deletes, sends or deploys. Clients confirm first. - `ask_finai`: Hand a task in words to Finai, Final's own agent, and get its finished answer. - `enable_packs`: List more packs for this connection. - `disable_packs`: List fewer packs to keep the tool list short. - `switch_company`: Choose the company Hub tools act on. #### Catalog (Hub, listed by default) Products, variants, categories, options, modifiers, product photos and the media library. - `hub_get_products`: Search and read products. - `hub_create_product`: Create a product. - `hub_import_products`: Import many products at once. - `hub_add_product_images`: Add photos to a product. - `hub_get_modifiers`: Read modifiers and their choices. #### Inventory (Hub) Stock levels and history, transfers, suppliers, purchase orders, reorder rules, stock CSV import and export. - `hub_find_low_stock`: Products below their reorder point. - `hub_get_reorder_suggestions`: What to reorder, and how much. - `hub_create_purchase_order`: Draft a purchase order for a supplier. - `hub_send_purchase_order`: Email a purchase order to the supplier. - `hub_record_received_goods`: Record a delivery against a purchase order. #### Orders, customers and reports (Hub) Orders are read-only: payments, refunds and voids happen on the till. - `hub_get_orders`: Search orders. - `hub_get_customers`: Search customers. - `hub_get_customer_orders`: A customer's order history. - `hub_get_financial_summary`: The financial summary for a date range. - `hub_get_sales_breakdown`: Sales broken down for a date range. #### Team, store setup and bookings (Hub) Team members, roles and permissions; outlets, stations, taxes and Hub extensions; bookable services. - `hub_get_team`: Team members and their roles. - `hub_create_role`: Create a role with its permissions. - `hub_create_tax_group`: Set up a tax group. - `hub_create_booking_resource`: Add a bookable resource, such as a therapist or room. - `hub_get_booking_availability`: Open slots for a bookable service. #### Build apps (Flow, listed by default) Build and deploy Final POS apps. Every file write is a restorable checkpoint in the Final builder. - `flow_get_scaffold`: The app contract and engine-owned files. - `flow_lookup_pos_api`: The Final POS REST API catalog, version-locked. - `flow_search_blueprints`: Vetted screen blueprints to start from. - `flow_write_flow_files`: Write files into the flow. - `flow_validate_flow`: Guardrails, typecheck and secret scan. - `flow_start_preview`: Boot a live HTTPS preview. - `flow_deploy_flow`: Deploy, after the same gates the builder uses. #### App data (Flow) Custom tables (the app's offline-capable database), the secrets vault and Flow extensions. - `flow_create_custom_table`: Create a table with typed columns. - `flow_request_secret`: Ask the owner to enter an API key in the builder; the value never passes through the agent. - `flow_list_extensions`: Org-owned and marketplace extensions. All 177 tools, with arguments, on GitHub: https://github.com/Final-Commerce/final-pos-mcp/blob/main/TOOLS.md ## Safety, permissions and privacy - **Your role still applies.** Every Hub call runs as the person who connected, and Hub checks their live role on each call. - **Packs are the permission.** The agent can only use the packs you allowed. Change them or disconnect at any time at ai.finalpos.com/connections; disconnecting revokes every token at once. - **Reads and writes are separate.** call_tool only runs tools that read. Anything that creates, changes, deletes, sends or deploys goes through call_write_tool, which clients confirm with you first. - **Money stays on the till.** Taking payments, refunding and voiding orders are not available over MCP. Orders are read-only. - **Secrets never pass through the model.** flow_request_secret asks you to enter an API key in the builder, never in the chat. - **Every call is logged, live.** The Connections page shows each connected client and every call it made as it happens, with a one-line summary of each session. - **Final doesn't see your conversation.** MCP clients send tool calls, not the chat around them. Final keeps the connection, its encrypted token and a redacted log of each call. ## Things to ask Paste any of these into a connected client. ### Reorder low stock Inventory: find what's running out and draft the purchase order. > Which products are below their reorder point at the Main Street outlet? Draft a purchase order for the usual supplier and show it to me before you send it. ### Week-on-week sales Reports: compare two periods by category. > Compare last week's sales by category with the week before, and tell me which categories moved most. ### Bulk catalog import Catalog: add many products with photos. > Add these 40 products from the attached spreadsheet, with photos, and tell me if any are missing a price or category. ### Top customers Customers and orders: who buys most, and what. > Who were my top ten customers this month, and what did they buy? ### Coffee-shop kiosk Flow: build an app and get a live preview. > Build a coffee-shop kiosk with a product grid, modifiers, a cart and card payments. Start from the closest blueprint, validate it, then give me a preview link. ## Integrating with the Final POS API? The Final POS Public API is documented at finalpos.com/docs. Agents connected to the Final MCP server don't need a separate docs server: with the build pack they look up REST endpoints with flow_lookup_pos_api and the command-frame API with flow_lookup_command_frame. Setups that still use Flow's direct endpoint (flow.finalpos.com/api/mcp with an sk_ key) keep working; new setups should use https://ai.finalpos.com/mcp, which includes Flow. ## Frequently asked questions ### What is the Final MCP server? It is the official MCP (Model Context Protocol) server for Final POS. One remote URL, https://ai.finalpos.com/mcp, lets an AI assistant read and manage a merchant's Final back office (Hub) and build point-of-sale apps (Flow). It has 177 tools in 10 packs and is listed in the official MCP Registry as com.finalpos/final. ### What happened to the Final Flows MCP server? It is now part of the Final MCP server. Flow's app-building tools are the build and build_data packs, next to the Hub back office, behind one sign-in. Existing setups on flow.finalpos.com/api/mcp with an sk_ key keep working; new setups should use https://ai.finalpos.com/mcp. ### Which AI tools can connect? Claude (claude.ai and Claude Desktop), ChatGPT, Claude Code, Cursor, VS Code with GitHub Copilot, Gemini CLI, Codex, and any other client that speaks Streamable HTTP MCP. There is a Claude Code plugin and a Gemini CLI extension that add the Final playbook too. ### Do I need an API key? No, if your client supports OAuth (Claude, ChatGPT, Claude Code, Cursor, VS Code, Gemini CLI): add the URL and sign in with your Final account. Codex and scripts use a fai_ connection key from ai.finalpos.com/connections. ### Can ChatGPT or Claude manage my Final POS inventory? Yes. Allow the inventory pack when you connect. The agent can check stock levels, find low stock, suggest reorders, draft and send purchase orders, and record received goods. ### Can an AI agent build a POS app on Final? Yes. With the build pack the agent creates a flow, writes the app against Final's version-locked APIs and vetted screen blueprints, validates it with the builder's own gates, and returns a live preview URL. You launch it from the Final builder, or the agent deploys it once you confirm. ### What is Ask Finai? ask_finai is a core tool that hands a task in plain words to Finai, Final's own AI agent. Finai runs as the connection's user, within the same packs, uses Final's tools itself and returns the finished answer, with a conversationId to continue the thread. ### Why does my agent only see a few tools? Clients put every listed tool into the model's context, and quality drops with long lists. A connection lists a few packs; the agent finds the rest with find_tools, runs reads with call_tool and writes with call_write_tool, or lists a whole pack with enable_packs. ### Is it safe to let an agent work in my account? Every Hub call runs as the person who connected, and Hub checks their live role on each call. The agent can only use the packs you allowed, reads and writes go through separate tools, clients confirm writes with you, secret values never pass through the agent, and the Connections page shows every call live. You can disconnect at any time. ### Can the agent take payments or issue refunds? No. Payments, refunds and voids happen on the till. Orders are read-only over MCP. ### Is there a cost? Connecting is free, and so are Hub reads and changes. App previews, deploys and Ask Finai jobs use credits, the same as doing that work in Final. ### Can I see the tools before I sign up? Yes. The server answers tools/list without a sign-in, the server card at https://ai.finalpos.com/.well-known/mcp/server-card.json lists every tool, and TOOLS.md on GitHub documents each one with its arguments. Calling a tool needs a Final account.