# SteelEngine MCP

Connect external MCP clients to SteelEngine with policy-aware tool access.

SteelEngine MCP exposes the SteelEngine platform to external editors and AI clients. It can build, test, deploy, and manage workflows and workspace resources from Claude.ai, Cursor, Claude Code, Claude Desktop, VS Code, and other MCP clients.

The canonical endpoint is:

```txt
https://steelengine.com/api/mcp/steelengine
```

Older clients configured with `https://steelengine.com/api/mcp/copilot` continue to work. Both URLs use the same authentication, discovery, authorization, and execution implementation.

## Transport

SteelEngine supports the MCP **2026-07-28** protocol using Streamable HTTP. Current clients send each request as a POST with the protocol metadata and matching `MCP-Protocol-Version`, `MCP-Method`, and, where required, `MCP-Name` headers. Tool calls return an SSE response stream that closes after the result; discovery can return JSON. Clients must accept both `application/json` and `text/event-stream`.

The server is stateless. It does not issue session IDs or provide a standalone GET stream. Older clients can continue using the legacy initialize exchange and JSON responses on the same endpoint. See the [MCP Streamable HTTP specification](https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/streamable-http).

MCP is the external client interface. SteelEngine Chat and scheduled assistants call the platform tool gateway directly inside the application, using the same domain catalog and execution permissions. Internal service tokens and shared-secret headers do not authenticate this MCP endpoint.

Chat runs its tool calls in the web process; scheduled Sub Agents run theirs in the Temporal Worker. Neither needs an MCP connection or an MCP API key to call these platform tools. Integration tools discovered through Chat's **Search integration tools** and **Run integration tool** also execute directly; those Chat tools are not part of the external MCP catalog.

Browser connections must use an allowed origin: the configured SteelEngine origin, `https://claude.ai`, `https://claude.com`, `https://chatgpt.com`, or an origin configured in `ADDITIONAL_TRUSTED_ORIGINS`. Non-browser clients can omit `Origin`.

## Authentication

SteelEngine MCP supports:

* **OAuth** for clients that support the MCP OAuth flow. The signed-in user is the policy principal.
* **Entra workload access tokens** for self-hosted deployment pipelines when installation trust is enabled. The registered application is the principal, with its own organization/workspace grants. See [Entra workload identities](/self-hosting/entra-workload-identities).

Workload callers with `workflow:read` can retrieve a retained deployment graph with `steelengine_workflows.get_deployment_version`. Supply the workflow ID and the version number as a string in `versionId`. The graph uses workflow export credential redaction. See [Verify a rollback before redeploying](/self-hosting/entra-workload-identities#verify-a-rollback-before-redeploying) for the comparison and deployment steps.

* **SteelEngine MCP API keys** sent in the `X-API-Key` header. The key owner is the policy principal and the key's grants are an additional scope cap.

Interactive OAuth access tokens must include the `mcp:tools` scope. That protocol scope permits use of the MCP endpoint; it does not grant access to SteelEngine resources.

### The API-key AND rule

An MCP API key never inherits more access than its owner:

```txt
owner has the required PBAC permission
AND key scope covers the workspace or workflow at the required level
= operation allowed
```

The read, write, and admin labels attached to API-key grants are transport-level ceilings retained for key compatibility. They are not SteelEngine roles and do not replace catalog permissions.

## Deployment Pipelines with Entra

Use `Authorization: Bearer <Entra access token>` at the same platform endpoint. Installation trust validates the token's tenant, API audience and required application role. The registered identity selects its organization and local grants; no human account or SteelEngine API key is required by this path.

The workload surface exposes selected operations from `steelengine_workspaces`, `steelengine_workflows`, `steelengine_tables`, `steelengine_env`, and `steelengine_knowledge`. It supports deployment operations, names-only environment listing, KB and logical database/table configuration with compatible column additions and archival cleanup, paused OAuth connector configuration and write-only workspace BYOK configuration through separate action grants. These configuration grants do not grant document content, search, independent row CRUD/query, ingestion, manual sync, credential enrollment or organization key management. Connector update authority also permits `pause_connector` on an idle connector, using its exact revision and retry key without accessing credentials; running syncs return a conflict. Connector changes remain paused pending human-authorized validation/activation. Provider deletion requires separate authority and may select existing organization fallback. `tools/list` reflects granted actions and publishes field hints; strict server schemas and current scope/permission checks apply on every call. Workspace creation and general organization administration are outside this surface. See the [operation matrix](/self-hosting/entra-workload-identities#exact-actions-and-minimum-grants) for exact fields and grants.

The Python deployer can acquire the resource token through Azure CLI in `AzureCLI@2`. The Node CLI is an optional verification/pilot client. A rejected workload token does not fall back to a browser session or API key.

## Claude.ai with OAuth

1. In Claude.ai, open **Settings → Connectors**.
2. Click **Add custom connector**.
3. Enter `https://steelengine.com/api/mcp/steelengine`.
4. Complete sign-in and consent in the browser.

SteelEngine advertises OAuth metadata from the endpoint's `WWW-Authenticate` challenge and issues refresh-capable OAuth 2.1 tokens.

## Generate an MCP API key

Use a key for clients that authenticate with headers:

1. Sign in to [SteelEngine](https://app.steelengine.com).
2. Open workspace **Settings → API Keys**.
3. Find **SteelEngine MCP** and click **Create**.
4. Enter a name and create the key.
5. Copy the key immediately; it is shown once.

The key uses the `sk-steelengine-...` prefix. A key created here carries its owner's full reach. On hosted SteelEngine, **Organization Settings → API keys** can also create a **SteelEngine MCP** key. Explicit workspace or workflow grants cap the reach of that key.

Among API key types, only a **SteelEngine MCP** key authenticates `/api/mcp/steelengine`. Workspace, Personal, and Organization API keys authenticate `/api/v1/*` and are rejected by the MCP endpoint with `401 invalid_token`. The SteelEngine MCP group is available on hosted and self-hosted deployments.

### Which key authenticates which endpoint

| Endpoint                                                                     | Accepted credentials                                                                                            |
| ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `/api/mcp/steelengine` (and `/api/mcp/copilot`)                              | OAuth, a SteelEngine MCP key, or an approved Entra workload Bearer token on an enabled self-hosted installation |
| `/api/mcp/serve/{serverId}`, private ([Workflow MCP](/mcp/deploy-workflows)) | OAuth bound to that server, or a Workspace, Personal, or Organization API key                                   |
| `/api/mcp/serve/{serverId}`, public                                          | None. The server ignores any credentials sent                                                                   |
| `/api/mcp/cost-offload`, when enabled                                        | OAuth bound to this endpoint; explicit per-user client-scope grants are also required                           |
| `/api/v1/*`                                                                  | Workspace, Personal, or Organization API key                                                                    |

Platform MCP and Workflow MCP do not share keys. `/api/mcp/serve/...` rejects a SteelEngine MCP key. `/api/mcp/steelengine` rejects a Workspace, Personal, or Organization key.

## Client configuration

### Cursor

Add `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "steelengine": {
      "url": "https://steelengine.com/api/mcp/steelengine",
      "headers": {
        "X-API-Key": "YOUR_STEELENGINE_MCP_API_KEY"
      }
    }
  }
}
```

### Claude Code

```bash
claude mcp add steelengine \
  --transport http \
  https://steelengine.com/api/mcp/steelengine \
  --header "X-API-Key: YOUR_STEELENGINE_MCP_API_KEY"
```

### Claude Desktop

Claude Desktop requires [`mcp-remote`](https://www.npmjs.com/package/mcp-remote):

```json
{
  "mcpServers": {
    "steelengine": {
      "command": "bunx",
      "args": [
        "mcp-remote",
        "https://steelengine.com/api/mcp/steelengine",
        "--header",
        "X-API-Key: YOUR_STEELENGINE_MCP_API_KEY"
      ]
    }
  }
}
```

### VS Code

Add `settings.json` or `.vscode/settings.json`:

```json
{
  "mcp": {
    "servers": {
      "steelengine": {
        "type": "http",
        "url": "https://steelengine.com/api/mcp/steelengine",
        "headers": {
          "X-API-Key": "YOUR_STEELENGINE_MCP_API_KEY"
        }
      }
    }
  }
}
```

For self-hosted deployments, replace `https://app.steelengine.com` with the deployment URL.

## Cost-Offload routing pilot

The separate `https://steelengine.com/api/mcp/cost-offload` endpoint offers `plan_task`: advice about which model tier to use and which work to delegate. It does not execute the task. The endpoint returns `503` until an operator enables it with `COST_OFFLOAD_CLIENT_SCOPES`; your account must also have an explicit grant in `COST_OFFLOAD_USER_SCOPES`. Connect using OAuth for this URL. Platform MCP API keys and OAuth tokens issued for other endpoints do not authenticate it.

Pass the task and an allowed `client_scope` to `plan_task`. Legacy HTTP clients must also pass `surface`: `claude-code`, `claude-desktop`, `claude-web`, `codex`, or `unknown` for an unsupported client. The tool schema marks this field required because a legacy HTTP connection does not retain initialization metadata between requests. Stdio and modern HTTP clients can infer it from their client metadata; an explicit value overrides that detection.

The Claude Code plugin routes searches to the read-only `offload-scout`, small mechanical edits to `offload-editor`, and routine implementation to `offload-builder`. Fast tasks involving 10 or more files move to the balanced tier by default; security-sensitive tasks stay on the frontier tier. Codex model names require operator configuration through `COST_OFFLOAD_SURFACE_MODELS`.

## Permission-aware discovery

MCP `tools/list` is built for the authenticated principal. A domain tool can be omitted when it has no usable operations, and an operation-based tool can advertise only the operations the principal can use in at least one reachable workspace.

For a principal with several workspaces, discovery is the union of potentially usable operations. It does not mean every advertised operation is allowed in every workspace.

MCP `tools/call` always authorizes the selected operation again against the resolved target. A call can be denied after discovery when:

* The target workspace is outside the role assignment's scope.
* The target is outside the API key's grants.
* A role or group assignment changed after discovery.
* An explicit deny applies.
* A required product entitlement or confirmation is missing.

Discovery is advisory least privilege, not an authorization token. Clients must handle `permission_denied` from every call.

## Server-wide PBAC authorization

Every advertised operation across all 15 `steelengine_*` domain tools declares one or more Permission Catalog requirements. The direct `list_workspaces` tool is catalog-authorized too. There is no MCP fallback that converts a role into a generic workspace read, write, or admin capability.

Call authorization resolves the real target before execution. Existing resources such as workflows, tables, knowledge bases, skills, credentials, and MCP servers are checked by resource ID. Collection actions such as creating a workflow or table are checked against the destination workspace, database, or knowledge base. Parent IDs are resolved before policy evaluation, so a database or knowledge base from another workspace cannot be smuggled through a permitted workspace.

Multi-target operations check every protected side. Workflow cloning requires source workflow read permission and destination workflow create permission. A file-backed table import or knowledge-base ingest also requires document read access. Workflow-backed jobs require workflow execution access, workflow-specific notifications require workflow read access, and MCP server creation checks every workflow added as a tool.

Catalog entitlements and ABAC predicates are preserved. Archived or deleted resources remain unavailable where the catalog declares lifecycle checks, and confirmation-sensitive actions receive the call's confirmation context.

## Example: Docs permission matrix

`steelengine_docs` shows how operations within one tool remain independently grantable:

| Operations                                  | Required catalog permission  |
| ------------------------------------------- | ---------------------------- |
| `list`, `read`, `glob`, `search`            | `workspace:read_documents`   |
| `write`, `download_external`, `materialize` | `workspace:create_documents` |
| `update`, `patch`, `rename`, `restore`      | `workspace:update_documents` |
| `delete`                                    | `workspace:delete_documents` |
| `list_folders`                              | `workspace:read_folders`     |
| `create_folder`                             | `workspace:create_folders`   |
| `rename_folder`, `move_folder`              | `workspace:update_folders`   |
| `delete_folder`                             | `workspace:delete_folders`   |

The key scope must also cover the workspace. Mutating operations require a key grant whose transport ceiling is high enough for the operation.

`steelengine_docs.delete` removes one document per call with `fileId`. The legacy `fileIds` argument is accepted only when it contains exactly one ID; a batch returns `invalid_params`.

Other domains follow the same model. Examples include `workflow:read` versus `workflow:execute`, `table:query` versus `table:update`, separate app publish/delete permissions, environment metadata versus secret-value access, and independent read/manage permissions for MCP servers and skills. See the [Permission Catalog Reference](/permissions/permission-reference) for the complete vocabulary.

## Environment operations

`steelengine_env` separates metadata, value retrieval, and writes:

| Workspace operation | Catalog permission                  | API-key transport ceiling |
| ------------------- | ----------------------------------- | ------------------------- |
| `list`              | `workspace:read_environment`        | Read                      |
| `get`               | `workspace:read_environment_values` | Admin                     |
| `set`, `delete`     | `workspace:manage_environment`      | Write                     |

The user who owns the key must also be authorized for the operation. A read grant does not match `read_values`, and a write grant does not authorize plaintext retrieval. Personal-value retrieval uses `organization:read_personal_secrets` and the existing API-key scope restrictions.

Workload identities support only names-only `list` and write-only `set`, with independent grants. They cannot call `get`, even when the identity owner can reveal values. Mutation results contain identifiers and status rather than secret values.

Successful value retrieval records an `environment.values_revealed` audit event with actor, scope, and counts, excluding values. Recording is best effort. MCP HTTP responses use `no-store`; environment operation failures return generic errors without raw exception details. See [secret access and execution limits](/credentials#reading-secret-values).

## Workspace membership uses role keys

The workspace membership operations use the PBAC role model directly:

* `list_members` returns each member's effective roles with direct, group, or organization-wide provenance.
* `invite_member` accepts `roleKey` and defaults to the seeded Viewer key, `workspace:read`.
* `update_member_role` requires `roleKey` and accepts seeded or custom role keys.
* The legacy `permission: read | write | admin` argument is rejected.

MCP callers cannot change their own workspace role. Membership calls still require `workspace:manage_members`, and last-admin and billing-account safeguards continue to apply.

## Conditional tool catalog

The server's domain catalog includes the following tools, but the list returned to a particular client is conditional:

| Tool                      | Resource area                                                        |
| ------------------------- | -------------------------------------------------------------------- |
| `steelengine_workspaces`  | Workspaces and membership                                            |
| `steelengine_workflows`   | Workflow editing, execution, deployment, versions, and folders       |
| `steelengine_docs`        | Workspace documents and document folders                             |
| `steelengine_tables`      | Tables, databases, schemas, and rows                                 |
| `steelengine_apps`        | Dashboard apps, pages, widgets, versions, and publishing             |
| `steelengine_knowledge`   | Knowledge bases, documents, tags, and connectors                     |
| `steelengine_jobs`        | Scheduled jobs and job logs                                          |
| `steelengine_env`         | Environment variables and BYOK keys                                  |
| `steelengine_credentials` | Credentials and OAuth authorization links                            |
| `steelengine_mcp_servers` | Workspace and workflow MCP connections                               |
| `steelengine_skills`      | Reusable workspace skills                                            |
| `steelengine_memory`      | Assistant memory                                                     |
| `steelengine_logs`        | Execution, workflow, job, and audit logs                             |
| `steelengine_platform`    | Blocks, triggers, tool search, documentation, and platform discovery |
| `steelengine_a2a`         | A2A agents                                                           |

When `steelengine_credentials` returns an OAuth connection link, open it in a browser and sign in with the SteelEngine account that requested it. Links under `/connect/` are single-use and expire after 30 minutes. See [Connecting from Chat or MCP](/credentials#connecting-from-chat-or-mcp) for expired links and account-switching guidance.

## Scheduled Sub Agents

An external client can create a prompt-based scheduled task with `steelengine_jobs` and `operation: "create"`. Supply the task instructions, schedule or lifecycle, and optional model and reasoning settings from the tool's current schema. The task appears as a **Sub Agent** on [Scheduled Tasks](/chat/tasks), where you can inspect its configuration and run history.

Each occurrence executes the saved instructions as the task's saved user, with current workspace, resource, credential, and model authorization. A run can make several model and tool calls. Creating a scheduled task does not invoke an interactive delegation tool; automatic delegation within Chat is currently disabled. See [Sub Agent](/sub-agent) for context, approvals, and retry behavior.

## Surface restrictions

Having a permission does not make every dashboard action available through MCP. Ordinary user/API-key MCP, Chat, scheduled Sub Agents and workflow tools cannot delete databases. A signed-in dashboard user or explicitly authorized workload can archive an empty database with `database:delete`; the workload configuration operation additionally requires an exact ID/revision, retry key and confirmation. Workload table cleanup rejects relationship dependencies and retains owned rows for restoration. See [logical database/table configuration](/self-hosting/entra-workload-identities#logical-database-and-table-configuration) for its narrower operation contract.

## Errors

All domain tools return a structured envelope. Authorization failures use:

```json
{
  "success": false,
  "error": {
    "code": "permission_denied",
    "message": "Forbidden",
    "details": {
      "permissionKey": "workspace:update_documents",
      "workspaceId": "workspace-id"
    }
  }
}
```

The permission key is included when the operation uses exact catalog authorization. Denials are audited with the tool, operation, target, and permission key when available.

Argument names are checked against the tool's published schema, top-level or inside `args`. An argument the tool does not declare is handled in one of two ways:

* **A probable misspelling:** the call fails with `invalid_params`, because ignoring a misspelled name would change what the operation does. That is a name whose closest match among this operation's own arguments is an argument the call does not supply under any accepted name, such as `targetWorkspaceId` on `clone` without `destinationWorkspaceId`.
* **Anything else:** the argument is removed before the call runs, so it has no effect, including on permission checks. The result's `warnings` names it and lists the accepted arguments. Treat this warning as an error to fix: unknown arguments will be rejected in a future release.

A rejected call's message names the unknown arguments, suggests the closest accepted name, and lists the operation's accepted arguments. `details` carries the same `unknownArgs`, `suggestions` and `acceptedArgs`:

```json
{
  "success": false,
  "error": {
    "code": "invalid_params",
    "message": "Unknown argument for steelengine_workflows.clone: targetWorkspaceId. \"targetWorkspaceId\" → did you mean \"destinationWorkspaceId\"? Accepted arguments: ...",
    "details": {
      "unknownArgs": ["targetWorkspaceId"],
      "suggestions": { "targetWorkspaceId": "destinationWorkspaceId" }
    }
  }
}
```

## Running an undeployed workflow

The `steelengine_workflows` operations `run`, `run_until_block`, `run_from_block`, and `run_block` use the active deployment by default. Set `useDeployedState: false` explicitly to run the saved draft.

A draft run executes every block it reaches for real, including blocks that write, send or delete. An MCP client's run is not checked for that first, so confirm with the user before running a draft that makes changes. Chat applies a stricter rule to the runs it starts itself; see [Creating Workflows](/chat/workflows#creating-workflows). `get_state` returns a `revision` that identifies the content of the saved draft together with its workflow variables. Pass it back as `expectedRevision` on a draft run to run only that exact draft: if the workflow or a variable has changed since, nothing runs and the failed result carries `draft_revision_mismatch` details with the current revision. The comparison is made on the draft the run loads, so nothing can change between the comparison and the run.

Use `run_draft_revision` to require revision checking when calling across server versions. This operation always runs the saved draft and requires `expectedRevision`. Servers that support it advertise it in `tools/list`.

If the client cancels a run request before SteelEngine has accepted the run for execution, the run is not started. Once it is accepted, it runs whether or not the client is still connected.

If no active deployment exists, the failed result includes `workflow_not_deployed` details with the workflow ID and two recovery options:

* `run_draft`: retry the run with `useDeployedState: false`.
* `deploy`: call `deploy_api` with the workflow ID and `confirm: true`, then retry the run.

The details also list any enabled draft triggers found that deployment would activate. Deploying can start schedules, webhooks, and polling triggers without another manual run. The trigger list can be empty when the draft could not be inspected, so inspect the workflow before choosing deployment. Neither recovery action happens automatically.

## Rate limits

SteelEngine rate-limits requests per authenticated user: a burst of 60 requests, refilling at 30 per minute. Excess requests return `429` with a `Retry-After` header. Within a request, the server authorizes catalog entries and runs tool calls at most four at a time. On hosted SteelEngine a single request may run for up to one hour. Workflow MCP servers have their own per-server limit. See [Deploy Workflows as MCP](/mcp/deploy-workflows).

## Troubleshooting access

1. Confirm the client authenticated as the expected user or key owner.
2. In **Organization Settings → Access → People**, inspect that person's effective roles for the target workspace.
3. Confirm the role includes the operation's catalog permission.
4. Check direct, group, inherited, and organization-wide provenance.
5. For API keys, confirm the key grant includes the workspace or workflow and a sufficient transport level.
6. Refresh the client's MCP tool list after an access change.
7. Treat a call-time denial as authoritative even if the operation remains in a cached client schema.
8. If Claude Code reports a **Dynamic Client Registration** failure when adding the server with an `X-API-Key` header, the endpoint rejected the key with `401 invalid_token` and the client fell back to OAuth discovery. Confirm the key is a SteelEngine MCP key, not a Workspace or Personal key, before troubleshooting OAuth.

## Common Questions

**Is SteelEngine MCP the same as Workflow MCP?**

No. SteelEngine MCP exposes platform operations for managing SteelEngine. Workflow MCP exposes workflows you deployed as callable MCP tools.

**Is /api/mcp/copilot still supported?**

Yes. It is a compatibility alias for the same implementation. New clients should use /api/mcp/steelengine.

**Do I need an API key for Claude.ai?**

No. Claude.ai can use the OAuth flow. The signed-in user's current PBAC roles determine resource access.

**Why does another team member see different operations?**

Tool discovery is principal-specific. Roles, assignment scope, group membership, explicit denies, and API-key grants can all change which tools and operations are advertised.

**Can I call an operation that is hidden from tools/list?**

A client can send any JSON-RPC request, but tools/call performs mandatory authorization. Hiding an operation improves least-privilege discovery; it is not the enforcement boundary.

**Why was an advertised operation denied?**

Discovery is a union across reachable workspaces and can be cached by the client. The selected target may not be covered, access may have changed, or a key scope or entitlement may block the call. Call-time authorization is authoritative.
