Hutte MCP

Overview

The Hutte MCP (Model Context Protocol) server exposes your Hutte projects, sandboxes, features, and scratch orgs directly to AI assistants — Claude, Claude Code, Cursor, Hermes, and any other MCP-compatible client. Once connected, you can discover and provision Salesforce development environments conversationally, and hand them straight to the local sf CLI.

What you can do:

• Discover your projects, including their Git repo, project type, and pool status
• List sandboxes, open features, and active scratch orgs across all projects or within one
• Read the full context of a feature — notes, issue reference, pull request, source-tracking revision
• Create a new sandbox feature (Git branch + sandbox pairing) from a chat message
• Claim a pre-warmed scratch org from a project pool, ready to use in seconds
• Authenticate a scratch org, feature, or sandbox with the local sf CLI in one step
• Open any org in the browser via a one-time login URL
• Terminate a scratch org when the work is done

Because authenticate_org hands the org to your local sf CLI, the Hutte MCP composes naturally with the Salesforce DX MCP server and with any tooling that runs sf commands — SOQL queries, metadata deploys, Apex test runs.

Prerequisites

• A Hutte account with access to at least one project
• Salesforce CLI (sf) installed locally if you plan to authenticate orgs

Connection Details

The Hutte MCP server is hosted — there is nothing to install locally. Point your client at the endpoint below.

Authentication

Hutte MCP accepts two kinds of credentials. Pick whichever your client supports.

OAuth (interactive clients)

Clients that can open a browser — Claude.ai, Claude Code, Cursor — should use OAuth. Hutte supports dynamic client registration, so there is nothing to pre-configure: add the server URL, and the client walks you through a Hutte sign-in and consent screen. Tokens are refreshed automatically.

Personal access tokens (headless and cloud agents)

Agent servers that run without a browser — Hermes, CI jobs, background agents — authenticate with a personal access token instead.

1. In Hutte, click your avatar in the top right → Profile Settings
2. Scroll to the API Keys card and create a token: give it a name and, optionally, an expiry date
3. Copy the token immediately — it starts with hut_ and is shown only once
4. Send it to the MCP endpoint as an Authorization: Bearer header

The same API Keys card shows each token's prefix and when it was last used, and lets you revoke a token at any time. Revocation takes effect immediately. A token carries the full access of the user who created it, so store it as a secret (environment variable or your agent host's secret store) rather than committing it to a config file.

Connecting a Client

Claude.ai

1. Open claude.ai → click your profile icon → Settings
2. Navigate to Connectors → Add custom connector
3. Enter the server URL: https://app.hutte.io/mcp
4. Click Connect and complete the Hutte sign-in when prompted

Claude Code

Run in your terminal:

claude mcp add --transport http hutte https://app.hutte.io/mcp

Then run /mcp inside Claude Code and choose Authenticate to complete the OAuth flow.

To share the server with your team, commit a .mcp.json in the repository root instead:

{
  "mcpServers": {
    "hutte": {
      "type": "http",
      "url": "https://app.hutte.io/mcp"
    }
  }
}

Cursor

1. Open Cursor Settings (Cmd/Ctrl + ,) → MCP
2. Click Add new MCP server
3. Set the URL to https://app.hutte.io/mcp
4. Save — Cursor prompts you to sign in to Hutte

Or edit .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "hutte": {
      "url": "https://app.hutte.io/mcp"
    }
  }
}

Hermes

Hermes reads its MCP configuration from ~/.hermes/config.yaml under mcp_servers. Add Hutte as an HTTP server with a bearer token — see the Hermes MCP documentation for the surrounding file structure.

mcp_servers:
  hutte:
    url: "https://app.hutte.io/mcp"
    headers:
      Authorization: "Bearer hut_your_token_here"

Replace hut_your_token_here with a token from Profile Settings → API Keys (click your avatar in the top right of Hutte to get there).

Other Agent Servers

Any client that can call a remote HTTP MCP server with a custom header will work. The pattern is the same everywhere: the endpoint URL plus an Authorization header.

{
  "mcpServers": {
    "hutte": {
      "type": "http",
      "url": "https://app.hutte.io/mcp",
      "headers": {
        "Authorization": "Bearer ${HUTTE_MCP_TOKEN}"
      }
    }
  }
}

Most clients support some form of environment-variable interpolation in the config file (${HUTTE_MCP_TOKEN}, ${env:HUTTE_MCP_TOKEN}, or similar — check your client's documentation). Use it so the token never has to be committed alongside your configuration.

To verify a token outside of any client, call the endpoint directly:

curl -s https://app.hutte.io/mcp \
  -H "Authorization: Bearer $HUTTE_MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Available Tools

Discovery

Provisioning

Org Access

Access Rules

The MCP server acts as you. Every tool is scoped to the projects your Hutte account can already see, and a few operations carry extra rules:

• Only active scratch orgs and open features can be authenticated or opened in the browser
• Authenticating a sandbox directly (via sandbox_id) requires the project admin role on that project. Team members work through features instead
• list_features and list_sandboxes only accept sandbox-type projects; list_scratch_orgs covers scratch org projects
• take_pool_org only works on projects that have an org pool configured
• create_sandbox_feature fails if the sandbox is not ready, or if it already has an open feature and the project does not allow parallel features
• terminate_scratch_org is irreversible — most clients ask for confirmation before running it, and you should leave that confirmation enabled

Usage

Exploring What You Have

"List my Hutte projects" "Show all open features for the ACME4 project" "What scratch orgs do I have active?" "Which sandboxes in ACME4 are free for a new feature?"

Picking Up a Piece of Work

"Read the notes and linked issue for the HUT-55 feature, then summarise what needs to be built"

The assistant calls get_feature, which returns the feature's notes and issue reference along with its branch, sandbox, and pull request — enough context to start working without you restating the ticket.

Creating a Sandbox Feature

"Create a feature called 'Account health score' in ACME4 on the most recently refreshed available sandbox, and link it to HUT-55"

The assistant calls list_sandboxes to pick an available sandbox, then create_sandbox_feature with the name, the issue reference, and — if you want one — an explicit branch name. Leave branch_name off and Hutte generates it from the feature name.

Authenticating an Org with the sf CLI

"Authenticate the Cleanup account page layout feature from ACME4" "Authenticate my scratch org for HUT-55"

The assistant calls authenticate_org and returns a shell command to run in your terminal:

echo "force://..." | sf org login sfdx-url \
  --alias "hutte-<feature-name>" \
  --set-default \
  --sfdx-url-stdin

The org is then available to all sf CLI commands under the alias shown.

Opening an Org in the Browser

"Open the ACME4 Cleanup account layout feature in the browser" "Give me a login URL for my HUT-55 scratch org"

The assistant returns a one-time Salesforce frontdoor URL. Open it immediately — it expires within minutes.

Claiming and Releasing a Pool Scratch Org

"Take a pool org from the ACME4 project and call it HUT-55 spike" "I'm done with the HUT-55 spike org — terminate it"

take_pool_org returns the org already authenticated-ready, so you can deploy to it within seconds instead of waiting for a fresh scratch org to be created. terminate_scratch_org deletes it permanently when you're finished.

Combined Workflows

The Hutte MCP tools compose naturally with Salesforce DX MCP tools and with your coding agent:

"Create a helper class that calculates an Account health score and a corresponding test class. Authenticate the 'Account Health Score' feature and deploy both classes. Execute the tests" "Take a pool org from ACME4, deploy the current branch to it, run all local tests, then terminate the org" "List my features, pick the one for HUT-55, open it in the browser"

Troubleshooting