Security and permissions

An assistant connected over MCP acts as a Beas user. What it can do is decided by three independent gates, and all three have to allow an operation before it happens. Understanding them in order is what makes the endpoint safe to expose.

The three gates

Gate	Set by	Effect
The configuration	EnableWriteTools and EnableODataQueryTool on the server	A tool that is switched off is not offered to anyone, whatever their permissions. This is the whole-deployment switch.
The authentication scheme	How the assistant connected	An API-key caller is read-only: write tools and the generic OData tool refuse it before permissions are consulted. A user session passes this gate.
The user's permission	The user's Beas authorizations	Each write tool demands the same Full Control permission the web client demands for the equivalent action.

The order matters when you are diagnosing a refusal. Configuration beats authentication, and authentication beats permissions — so "the user is an administrator" explains nothing on its own.

Why write tools cannot outflank the web client

Each write tool resolves the user's permission through the same policy the REST controllers use, so a user who cannot create a work order in the web client cannot create one through an assistant either. The gate is not a re-implementation that might drift: it is the same check, given the same resource name and the same required level.

Tool	Permission required
work_orders_create, work_orders_update	Full Control on Work Orders
production_times_create	Full Control on Active Work Order Times
resource_downtimes_create	Full Control on Resources

The API key

API-key access uses the BeasWebServerKey value from the Beas setup, with headers naming the company database and the user code to act as.

caution

This is one shared, long-lived server key, not a credential you issue per assistant. Anyone holding it can read the data of any company database the server can reach, under any user code they name, and revoking access for one consumer means changing the key for all of them. Keep it on the server side, and prefer a user session for anything interactive.

Its one structural safeguard is that it cannot write: the write tools and beas_odata_query both require a session, and both say so plainly when refused.

What errors reveal

A tool that fails returns a message written for the assistant to act on. Business problems come back in full — a record that does not exist, a validation rule, a required change reason, a failed operation — because the assistant, or the user reading its answer, can do something about them. Anything unexpected comes back as a general statement that an internal error occurred, with the detail going to the server log instead. No stack trace or internal detail reaches the client.

Before you enable it

1. Decide whether write tools should be available at all in this deployment. They are on by default. Switching them off makes the endpoint read-only for everyone, which is the right starting point for a first rollout.
2. Decide whether the generic OData query tool should be available. It is also on by default and widens read access to every entity the API exposes, well past the curated tool list.
3. Decide how assistants authenticate, and keep the API key server-side.
4. Review who holds Full Control on Work Orders, Active Work Order Times and Resources — those users' permissions are now also what an assistant connected as them can do.
5. Switch VerifySSL on for a hardened deployment. It is off by default so a self-signed development certificate does not block the server's own loopback call.

Examples

A read-only rollout that still answers most questions. Leave Enabled on, switch EnableWriteTools off, and leave EnableODataQueryTool on. The assistant keeps all 68 read tools and the generic query, and no configuration mistake or over-permissive user can change data, because the write tools are not published at all.

A refusal that names a permission the user does have. The message quotes the resource and the level the operation needs. If the user genuinely holds that level, they are connected with the API key rather than a session — the read-only gate produces a refusal that mentions permissions because it is the same message path. Reconnect with a user session.

Related functionality

• Connecting — the configuration settings and the two authentication schemes.
• Authorizations — how Beas permissions are granted.