OAuth and the AI interface (MCP)

This page explains how you can safely give external programs — for example AI assistants — permission to read and update your BrewOS account's data. The guide is meant for all users and does not assume any prior technical knowledge. We go through things calmly and thoroughly.

In short: what is this about?

BrewOS is usually used in a browser: you sign in, click through the menus and view or edit the data yourself. Sometimes, though, it would be handy if some other program could do part of the work for you. Examples:

You ask an AI assistant (such as Claude or similar) to list which products are in stock, or to record a new customer — and it does it for you.
One of your company's own systems automatically fetches sales figures from BrewOS.
An automation tool records measurement results for a production batch.

To make this possible, two things are needed:

An interface — a "door" through which another program can talk to BrewOS. This door always exists, and its technical name is MCP (Model Context Protocol). You do not need to know any more about MCP than that — it is simply a common way for AI tools to connect to services.
Authorisation — the permission you give at the door by signing in and approving access. Without authorisation the door stays locked.

Authorisation is given by signing in with OAuth: the tool directs you to the BrewOS sign-in page, and you approve the access. There is no key to copy or store by hand. The rest of this page explains how to set up the connection and how to manage the access you have granted.

The key principle: the connection works with your permissions

This is the most important part of the guide, so read it carefully.

When you approve an application's access, the application works with exactly your permissions — no more and no less. It does not get a separate ID of its own; it acts in your name:

If you have permission to see customers, the application's requests see them too.
If you do not have permission for some section, the application cannot get there either.
Access is always tied to one account (company). It cannot reach the data of other accounts, even if you have permissions on several accounts.

Permissions are checked again every time. If your role changes, the application immediately gets the permissions of your new role. If you are removed from the account, all access you have granted to that account stops working immediately. So the application can never do more than you yourself can do right now.

Permission levels

When approving access, you choose how much power the application is given. The options are:

Read only — the application can only view data (e.g. list products or customers). It cannot change anything. This is the safest option, and you should use it whenever reading data is all that is needed.
Read and write — the application can both view and edit data: create customers, record payments, start production batches and so on. Only give this level to tools you trust.

Even if you choose "read and write", access is still limited to your own permissions and to the chosen account — the level choice can only narrow permissions, never widen them.

How to connect a tool

Most modern AI tools support OAuth out of the box. Proceed as follows:

Add a new connection (connector / MCP server) in the tool and give it just the interface address:
```
https://brewos.fi/mcp
```
You can also see the exact address on the Settings > AI agents page under Connecting an agent. It is always /mcp appended to your BrewOS address.
The tool opens a BrewOS sign-in window. Sign in as usual (email, password and, if required, an OTP code).
On the approval page, choose under Account the account you are giving access to, and under Permission level either Read and write (the default) or Read only. Finally, press Allow access. The Cancel button stops the connection.
The tool returns automatically and is ready to use straight away. There is no key to copy, and the tool renews the access automatically in the background.

Granted access is valid for at most 60 days. After that the tool asks you to sign in and approve the access again.

You can then ask the tool, for example: "List the active products in my BrewOS account" or "Add a new customer called Esimerkki Oy", and it will handle the request through the interface.

For technical users. The OAuth implementation follows OAuth 2.1: the server publishes metadata at /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server, supports dynamic client registration (/oauth/register), PKCE (S256) and the authorizationcode and refreshtoken grants. You do not need these details if your tool handles OAuth for you.

What can be done through the interface?

The interface offers a set of tools that correspond to BrewOS's various functions. Which tools an application can use depends on your role and on the chosen permission level: a Read only connection sees only the read tools.

In broad terms, the following are available:

Account and products – the account's basic details, product search and details, product groups, creating and editing products, multipacks and pricing.
EAN codes – EAN number ranges and codes, code validation, reserving the next free code and linking it to a product.
Customers – searching, creating and editing customers, delivery locations, customer groups, export customers and creating a customer from Valvira's licence holder register.
Recipes and production – recipes with their steps and ingredients, starting production batches, state changes, ticking off steps, notes, measurements and packaging.
Warehouses – balances and movements of raw material and finished product stock, raw material receipts, stock corrections and stock counts, transfers of finished products and raw materials between warehouses.
Shipments – creating shipments, product rows, picking, marking as delivered, cancelling and shipment documents.
Invoicing and payments – creating invoices from a shipment or separately, invoice rows, activating an invoice, credit notes, and recording and allocating payments.
Reports – e.g. sales, shipment, invoice, payment, production and stock reports, accounts receivable, the EU sales list, Valvira reports and batch traceability.
EMCS – sending electronic administrative documents (e-AD) for export shipments, checking their status, recording receipt and cancelling.
Tanks – tank details and condition, reservations and moving a batch into a tank.
Taxes and authority reports – tax events and their correction, products' excise details and checking Valvira reports for missing information.
Event log – reading the account's events.

Some tools take actions that have consequences outside BrewOS or that cannot be directly undone. For example, the EMCS tool sends the administrative document to the Finnish Tax Administration (Vero) when Vero's EMCS interface is in use. Marking a shipment as delivered creates tax account events and consumes licence litres, and an activated invoice can only be corrected with a credit note. Always check what the AI assistant intends to do before you approve such an action.

The tool can ask the interface itself which functions are available, so you do not need to learn the list by heart. You can simply tell the tool what you want to do. The interface also gives the AI assistant ready-made instructions for the most common multi-step tasks, such as delivering a shipment, sending an invoice, stock changes, packaging, EMCS and authority reports, and setting up a customer.

Sales users. A sales user's connection has only a limited set of tools available: the account's basic details, product and product group details and the warehouse list. Customer, shipment, invoicing, pricing and production tools (including production batch notes) are not available to sales users.

Managing connected applications

The Connected AI agents section of the Settings > AI agents page lists the applications to which you have granted access on this account. For each one you see:

AI agent or application – the application's name
Permissions – Read only or Read and write
Last used – when the connection was last used
Valid until – when the application's current access expires. The tool renews the access automatically in the background until the maximum of 60 days is reached.

You can revoke any access with the revoke button at the end of the row and by confirming the revocation. The application loses access immediately. This is useful, for example, when you stop using a tool or suspect that it can no longer be trusted.

Each user sees and manages only the access they have granted themselves. Not even the owner can see or revoke access granted by other users. If a user is removed from the account, all access they have granted to that account stops working.

Opening the page. The Settings menu is visible only to the account's owners. An owner opens the page by choosing settings and the AI agents tab. Other users do not see a link to the page in the menu, but they can open it directly from the browser's address bar: append /asetukset/ai_agentit to the account address after the account number, for example https://brewos.fi/123/asetukset/ai_agentit, where 123 is your account number. You can see the account number (id) on the Accounts page, which you open with the accounts link in the top bar. A sales user can also open the page this way.

Security

A few important things that keep your account safe:

Use the lowest sufficient permission level. If the tool only needs to read data, choose Read only.
Only approve access for tools you recognise. Always check on the approval page which application is requesting access.
Revoke access as soon as the tool is no longer in use.
Changes made through the interface are recorded in the account's event log in your name, in the same words as the corresponding change on the BrewOS pages, with the note (MCP) at the end of the row, for example Linked EAN code … to product … (MCP). The entry is also shown in the own event log of the changed product, shipment, invoice etc., so you can check afterwards what the connections have changed. Only successful calls that change data are logged; plain reads of data, failed calls and calls that changed nothing are not.
Usage is rate-limited (at most 120 requests per minute per connection), which prevents accidental or deliberate overloading. In normal use you will not run into the limit.

Frequently asked questions

Do I need technical skills? No. You give the tool the interface address, sign in and approve the access — the rest happens automatically.

Do I have to copy or store some key? No. The tool obtains and renews the access itself through OAuth.

Can the application see the data of my other companies? No. Each access is tied to one account. If you need the interface for several accounts, approve access separately for each account.

Can the application do more than I can? Never. It works with your permissions, and the permissions are checked on every call.

My tool does not support OAuth. What do I do? Contact support. Connecting to the AI interface with fixed API keys is no longer possible.

What about our own webshop? A webshop does not use the AI interface but its own webshop API. The account owner creates an API key for the webshop on the Settings > Webshops page: the key is shown only once, and it can be revoked on the same page. There is a separate developer guide for the person building the webshop, and you can send them the link directly.

How do I disconnect? Open the Settings > AI agents page (see above), find the application in the list and press revoke.

This guide relates to the Settings > AI agents page. See also Accounts and users, Security and Event log.

Page last updated 23 Oct 2026 11:24