Salt MCP reference
Reference the Salt MCP endpoint, OAuth access, capability groups, prerequisites, defaults, and common errors.
Use this reference to understand how an MCP client connects to Salt and which capabilities become available after authorization. Salt MCP exposes a remote, stateless tool server, while Salt continues to enforce your account permissions on each operation.
Server
| Property | Value |
|---|---|
| Production endpoint | https://salt-api-prod.salt.ai/mcp |
| Transport | Streamable HTTP |
| Session model | Stateless HTTP |
| Authentication | OAuth bearer token |
An unauthenticated request returns HTTP 401 with a WWW-Authenticate header that points the client to Salt's OAuth metadata. The response includes:
Missing bearer token. See WWW-Authenticate header for the OAuth metadata URL.MCP clients use that metadata to discover Salt's authorization, token, registration, revocation, and introspection endpoints.
OAuth behavior
| Property | Supported behavior |
|---|---|
| Grant types | Authorization code and refresh token |
| Authorization response | Authorization code in the query string |
| Proof Key for Code Exchange (PKCE) | Required, using S256 |
| Dynamic client registration | Supported |
| Client ID metadata | Supported |
| Bearer token location | Authorization request header |
| Default scope | read |
| Available scopes | read, write |
Scopes
| Scope | Access |
|---|---|
read | Reads data from your Salt account, including Pipelines, nodes, deployments, and knowledge bases. This is the default scope. |
write | Changes data in your Salt account and runs Pipelines on your behalf. It also includes read access. |
Salt maps downstream Salt API methods used by tools to a minimum OAuth scope. These methods do not describe the Streamable HTTP request that carries MCP messages.
| Methods | Required scope |
|---|---|
GET, HEAD, OPTIONS | read |
POST, PUT, PATCH, DELETE | write |
When a token does not include the required scope, Salt returns HTTP 403 with:
OAuth token lacks the '<scope>' scope required for <METHOD>.The scope grant does not replace Salt permissions. A client can access only the resources and operations that the signed-in account can access.
Authorization screen
Salt displays the authorization request in the browser before granting access.
| State or element | What Salt displays |
|---|---|
| Loading | Loading… |
| Consent title | Authorize app |
| Client identity | The client name followed by wants to access your Salt account |
| Callback | Connects back to followed by the redirect origin, when available |
| Client source | Identified by followed by the source, when available |
| Account | Signed in as followed by your email address |
| Decisions | Cancel and Authorize |
| Newly registered client | Newly registered. Verify the URL above matches the tool you're connecting before continuing. |
| Authorization failure | Cannot authorize, the error detail, and Close this tab and return to the app that opened it. |
The screen lists a description for each requested permission. For a newly registered client, verify that the displayed callback matches the application that opened the authorization page before granting access.
Capability groups
Your account permissions and provisioned Salt services determine which operations you can use.
| Capability | What it covers | Additional requirements |
|---|---|---|
| Account context | Read the signed-in user's Salt profile. | Authenticated Salt account |
| Pipeline discovery and management | List, search, inspect, create, update, duplicate, rename, delete, compare, summarize, share, and unshare Pipelines. | Write scope for changes |
| Canvas building | Add and remove nodes, set values and titles, create Edges, organize groups, add notes, and adjust layout. | Write scope |
| Runs and artifacts | Start or cancel a Pipeline run, inspect status, list prior runs, and retrieve artifacts. | Write scope to start or cancel; a runnable Pipeline with a terminal output to start |
| Node registry and documentation | List built-in nodes, inspect schemas, and read node descriptions and documentation. | Authenticated Salt account |
| Custom-node authoring | Create, inspect, edit, validate, build, and reload custom-node code. | A custom-node pack named custom_nodes; some operations also require a provisioned runner |
| Connections and credentials | Inspect connection definitions and manage credentials and data-source connections. | Permissions for the requested resource; write scope for changes |
| Knowledge bases | List, inspect, search, create, update, and manage knowledge bases and their documents. | Permissions for the requested knowledge base; write scope for changes |
| Model Vault and model deployment | Work with catalog entries, drafts, deployment state, inference, quotas, keys, and deployment operations. | Model Vault access and the permissions required by the requested operation |
Pipeline and runner prerequisites
Pipeline execution requires a runnable Pipeline with at least one terminal output. A Pipeline without a terminal output cannot produce a result.
Tools that inspect or operate a personal runner require a provisioned runner. If no runner is provisioned, runner-dependent tools can return NO_RUNNER_POD.
Custom-node tools require the authenticated account to have a custom-node pack named custom_nodes.
Selected tool defaults and limits
These defaults affect common listing, search, and deletion operations. Clients can discover the full input schema for each tool from the MCP server.
| Tool | Parameter | Default | Accepted behavior |
|---|---|---|---|
workflow_list | limit | 20 | Clamped to 1 through 500 |
workflow_search | limit | 20 | Returns up to the requested number of matching Pipelines |
workflow_executions | limit | 20 | Clamped to 1 through 500 |
kb_search | size | 5 | Clamped to 1 through 50 |
workflow_delete | dry_run | true | Reports what would be deleted; deletion occurs only when dry_run is false |
Troubleshooting
| Symptom | Meaning | Check |
|---|---|---|
HTTP 401 with Missing bearer token... | The request did not include an OAuth bearer token. | Confirm that the client follows the WWW-Authenticate metadata challenge and completes browser authorization. |
Cannot authorize in the browser | Salt could not complete the authorization request. | Read the error detail on the page, then return to the client that opened it. |
HTTP 403 with OAuth token lacks... | The granted scope does not cover the backend method used by the tool. | Read operations need read. For changes or runs, enable write access; reconnecting without changing a client pinned to read still requests read-only access. |
A Pipeline run fails with prompt_no_outputs | The Pipeline does not contain a terminal output. | Add a terminal output to the Pipeline before running it through MCP. |
NO_RUNNER_POD | A runner-dependent tool cannot find a provisioned personal runner. | Confirm that your Salt environment has provisioned a runner for your account. |
| A capability is unavailable or rejected | The signed-in account does not have the required product access or resource permission. | Confirm access to the corresponding Salt area and resource. |