Role scope
Narrow the tools your agent offers a caller down to the ones that match their role.
An agent connected to several MCP servers can end up with a large set of tools. Role scope narrows that down per caller: someone only gets offered the tools tagged for their role, so the agent picks from a smaller, more relevant set, which makes it both faster and less likely to reach for the wrong tool.
This is a performance and UX improvement, not access control. It doesn't mean you can relax your own rules: every tool still calls your API exactly as configured, and your API always has to check permissions itself, the same as it would for any other caller.
How it works
Tag the operations in your OpenAPI document with x-role, see
Role management.
Call the agent's chat endpoint with an Authorization header
carrying a JWT (JSON Web Token), Authorization: Bearer <token>, see
Authentication.
Tuix AI Agents reads the custom_roles claim from that token, a
list of role strings, and uses the first entry as the caller's role.
Filtering
With a role resolved, the agent only offers tools whose x-role metadata
includes that role, matching if at least one of the tool's roles applies. A
tool with no x-role at all isn't restricted, it's offered to every caller
regardless of role.
Authenticating with an X-Api-Key instead of a user's own Authorization
token means there is no per-user token to read a role from, so no
filtering applies and the agent sees every connected tool.