Managing access to Gearset MCP tools with roles

Role-based access control (RBAC) lets team owners manage access to Gearset MCP tools through the roles assigned to team members. For example, you can allow developers to query pipelines and validate PRs, while giving release managers access to promotion and release tools.

This guide applies to teams with RBAC for MCP enabled. For instructions on connecting your MCP client, see Getting started with the Gearset MCP.

There are two levels of permission:

For a team member using a personal access token, both must allow a tool before it can be used.

For example, your role might allow you to query pipelines, validate PRs, and promote changes. If you create a token with only query and validation tools selected, your MCP client won’t have access to promotion tools.

MCP tool permissions also work alongside your existing Gearset permissions. Access to a promotion tool doesn’t give you permission to promote into an environment you don’t otherwise have access to.

You must be a team owner to create or edit roles, including the MCP tools they grant access to.

Consider the full task when choosing tools. Someone who validates PRs will also need tools to find the PR, check validation status, and investigate failures. If a user has multiple roles, they can use the tools granted by any of those roles. Leaving a tool unselected in one role doesn’t remove access granted by another.

Once your role permissions are in place, go to Access token management and create a Personal token. Under API scopes, the MCP section lists the tools your roles allow you to select.

Hover over a tool name to see its description, then tick the tools your MCP client needs. Your client will only see and use the tools selected on that token.

You still need the Create API Personal Access Token permission to create a token. Being granted MCP tools through a role doesn’t grant this permission automatically.

Follow the Gearset MCP setup guide to connect your MCP client using the token.

A token keeps the tool selection made when it was created. Gearset also checks your current role permissions when your MCP client requests the available tools or calls a tool.

Removing access through your roles prevents an existing token from using the affected tools. Access remains available when another assigned role still grants it.

Restoring role access lets an existing, valid token use the tool again, provided it was already selected on that token. You do not need a new token just because a role permission was removed and restored.

Adding a tool that is not selected on your token requires a new token. First make sure your roles grant the tool, then create a token containing it and update your MCP connection. The same applies when you want to use newly released tools.

A token can remain active and unexpired while having no tools available under your current role permissions. Its saved tool selection does not, by itself, show what it can currently use.

Team owners don’t need role assignments to use MCP tools, but their personal tokens are still limited to the tools selected when they create them.

Shared team tokens use the tools selected on the token rather than an individual team member’s role permissions. Changes to a team member’s roles therefore don’t affect a shared team token.