What is the Gearset MCP?

Introducing the Gearset MCP, a new way to manage your Gearset directly from your IDE and AI coding assistant, without switching to the Gearset UI.

The Gearset MCP (Model Context Protocol) server lets your AI coding assistant talk directly to Gearset. If you are already building changes with tools like Claude Code or Cursor, you can now query your pipelines, validate changes, and promote a pull request without leaving your development environment.

What does it do?

This first version of the MCP is intentionally lightweight. It focuses on the Pipeline actions that fit most naturally into a coding session:

Query pipelines: ask your AI assistant about the state of your pipeline and the environments within it, so you can see where your changes are without opening the UI.
Validate a PR: run a validation against the target environment to check that your pull request will deploy cleanly.
Promote a PR: promote a pull request through your pipeline once you are happy with it.
Create releases: add features to your release and promote it into your production environment.

Because these actions run through the MCP you can drive them in natural language from inside your IDE. For example, you can ask your assistant to check the status of your pipeline, validate the PR you have just opened, and then promote it, all in the same flow as writing the code.

Who is this for?

This is for Salesforce teams who are already building changes with an AI coding assistant such as Claude Code or Cursor, and who want to manage their pipeline from within the IDE rather than navigating to the Gearset UI.

If you spend most of your time in your editor and only jump into Gearset to move a change forward, the MCP is designed to keep you in that single environment. You stay in your development context, and your pipeline actions happen right alongside your code.

Prerequisites

Automation Teams or above

Limitations

Only supports local agents for now, e.g. Claude Code, VSCode + Copilot, ChatGPT / OpenAI Codex CLI
- This is due to our Bearer token authentication method which is not supported in the web versions
- We're working on improving the experience here to also enable more web-based clients.

Getting access

Connecting to the Gearset MCP

Authenticate using access tokens via Bearer authentication. You choose which MCP tools each token can call, so if you tick Get All Pipelines, Get Promotion Status and List Deployments, your LLM can only see and use those three, and won't have access to Promote Pull Request or any other tool you haven't granted.

Enable access tokens

This step must be completed by a team owner

In My account, go to the Gearset Permissions page and enable the Create API Personal Access Token option.

Manage access to MCP tools through roles

For teams with RBAC for MCP enabled, a team owner must also grant the tools you need through your assigned roles. Permission to create a token does not automatically grant access to MCP tools. Team owners do not need role assignments.

See Managing access to Gearset MCP tools with roles for details.

Create your access token

Go into My Account and then into Access token management
Under API scopes you'll see an MCP section listing every tool, grouped. Tick the tools you're interested in — ticking a group name selects everything in it, and ticking MCP selects everything. Hover a tool name to see what it does.
- Your LLM only sees the tools you've ticked, so a token with only query tools granted won't be able to access the write tools at all.
- Choosing which tools to grant. Start from the task you want your assistant to do, then include the query tools that feed it.
Create this as a new Personal token, and give it a meaningful name so you can track it.
- A token's tools are fixed once it's created — you can extend its expiry date later, but to grant a different set of tools you'll need to create a new token and replace the old one.
A modal will appear with your new Access token - your token will only be viewable this one time so you should copy it out and store it somewhere secure like 1Password.

Changing access later

You cannot edit a token’s tool selection after creation. To include a tool that was not selected, create a new token and update your MCP connection.

Your current role permissions still apply to an existing token. Removing access through your roles prevents you from using the affected tools, even when they remain selected on the token. Restoring that access lets the same valid token use them again.

Connecting to your agent

You need a few key details for this to work:

The MCP URL, which will be based on the region your team is in:
- EU: eu.app.gearset.com/mcp
- US: us.app.gearset.com/mcp
- CA: ca.app.gearset.com/mcp
Your access token created in the step above

You can likely prompt your agent to help set up the new MCP for you, for example

Connect to a new MCP called Gearset with the URL of <URL for your region>. It requires a bearer authorization header, prompt me to enter it. This connection should be local to this project.

You should take precautions to not check this file into your version control system as it will contain your access token. If you do so, we recommend rotating your access token by deleting the access token from your account and creating a new one.

Claude Code manual steps

If it doesn’t already exist, create a new .mcp.json file in the folder where you’ll be running Claude Code from.
The basic structure of the file is as follows:
```
{
    "mcpServers": {}
}
```

Add a definition for the Gearset MCP as a new entry in the mcpServer object so the file looks like this. Note that the Authorization value still has the Bearer prefix - make sure this still exists in front of your access token when you add it in.

{
    "mcpServers": {
        "gearset": {
            "type": "http",
            "url": "<URL for your region>",
            "headers": {
                "Authorization": "Bearer <Access token you created earlier>"
            }
        }
    }
}

Now enter Claude Code and you should see a new MCP appear. You may need to activate the connection, so use the /mcp command and activate it through there.

Codex manual steps

If it doesn't already exist, create a .config.toml file in the folder where you'll be running Codex from.
Add an entry for the Gearset MCP server with the following format, placing your region-specific URL and the access token in. Note that the Authorization value still has the Bearer prefix - make sure this still exists in front of your access token when you add it in.
```
[mcp_servers.gearset]
url = "<URL for your region>"
http_headers = { Authorization = "Bearer <Access token you created earlier>" }
```
Now enter codex and you should see a new MCP appear. You can use the /mcp command to see all the tools that are now available to use.

Tips and tricks

It's useful to point your agent to our branching model documentation and have it summarize the concepts to a shared context file (e.g. CLAUDE.md or AGENTS.md, depending on your agent of choice) so it has context of the nuances of how a Gearset Pipeline works.

Getting started with the Gearset MCP