Skip to main content
Unlisted page
This page is unlisted. Search engines will not index it, and only users having a direct link can access it.
Version: 11.3.0

Controlling MCP Tool Access by Role

The MCP tools an agent can use through HYPR AgentPass™ follow its supervisor's role. An agent's reach therefore stays aligned with the authority of the person it acts for. Tool access is the third section of the role editor, beside the console permissions covered in Roles and Permissions.

How Role-Based Tool Access Works​

Every agent has a supervisor, the person it acts on behalf of, and every supervisor has a role. AgentPass uses that role to decide which MCP tools the agent may work with. The gateway applies the role's permissions in two complementary ways:

  • Tools are advertised by role. When an agent asks the gateway which tools are available, AgentPass returns only the tools the supervisor's role may call. Other tools are not listed, so an agent is never offered a tool it may not use.
  • Tool calls are checked by role. When an agent calls a tool, AgentPass confirms the supervisor's role permits the call before it reaches the tool. The gateway stops a call the role does not permit.

Both read the same role permissions, so they always agree. An agent is never shown a tool it cannot call, and never blocked on a tool it was shown.

The AgentPassAdmin role has access to every tool, and is not configurable.

Service agents carry their own role

A service agent runs with nobody at the keyboard, so it has no supervisor to take a role from. It carries a role of its own instead, and its tools follow that role through the same grid. Set them on the role you assigned to the service agent.

What an Agent Sees​

When an agent lists the tools on a gateway MCP server, the result reflects its supervisor's role:

  • If the supervisor's role may call a tool, the tool appears in the list, and the agent can call it.
  • If the supervisor's role may not call a tool, the tool is missing from the list the agent receives.
  • If the supervisor holds AgentPassAdmin, every tool on the server appears.

The gateway still reaches the MCP server behind the scenes, and your visibility and audit records still reflect the full set of tools. Only the list handed back to the agent is trimmed to what the role permits.

Role-based tool access applies automatically to the MCP servers the gateway hosts. Agents need no reconfiguration, and supervisors take no extra step.

Set Which Tools a Role Can Use​

  1. Open Oversight → People, and click the Roles tab.
  2. Click Edit on the role, and go to Agent tools permission. Tools are grouped by the connector that provides them, so you work through one MCP server at a time.
  3. Expand a connector to see its tools.
  4. Select a tool to permit it, or clear it to withhold it.
  5. Save. Changes take effect immediately.

The count beside each connector shows how many of its tools the role may call, so you can read a whole catalog at a glance without expanding it. For a large catalog, use the search box to narrow the list to one connector. Permit all and Clear all set every tool on a connector at once.

The per-role tool permission grid, with one expandable section per connector and a search box

A tool you withdraw stops being offered, and stops being callable, on the agent's next request. Nothing needs restarting, and supervisors do not need to sign in again.

Default Access and Overrides​

Every tool has a default access, which applies to any role you have not made a decision about. What you set on this tab overrides that default for this role. A tool that differs from its default is flagged, so you can see where a role departs from the norm. Reset to defaults removes your overrides for a connector, and returns its tools to their default access.

New tools are discovered without access. A tool that appears when a connector's catalog grows stays out of reach until you decide it belongs to a role. Review tool access when you add a connector, and when an MCP server you use gains new capabilities.

Grant what the work needs

Grant a role the tools it needs for its work, not the tools it might one day need. An agent is never shown a tool its supervisor's role cannot call, so a narrow grant also keeps the agent focused on the tools that matter to its task.