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:

https://dev.steelengine.com/api/mcp/steelengine

Older clients configured with {{API_URL}}/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.

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.

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 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:

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 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 {{API_URL}}/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.
  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

EndpointAccepted 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)OAuth bound to that server, or a Workspace, Personal, or Organization API key
/api/mcp/serve/{serverId}, publicNone. The server ignores any credentials sent
/api/mcp/cost-offload, when enabledOAuth 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:

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

Claude Code

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

Claude Desktop

Claude Desktop requires mcp-remote:

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

VS Code

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

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

For self-hosted deployments, replace {{APP_URL}} with the deployment URL.

Cost-Offload routing pilot

The separate {{API_URL}}/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:

OperationsRequired catalog permission
list, read, glob, searchworkspace:read_documents
write, download_external, materializeworkspace:create_documents
update, patch, rename, restoreworkspace:update_documents
deleteworkspace:delete_documents
list_foldersworkspace:read_folders
create_folderworkspace:create_folders
rename_folder, move_folderworkspace:update_folders
delete_folderworkspace: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 for the complete vocabulary.

Environment operations

steelengine_env separates metadata, value retrieval, and writes:

Workspace operationCatalog permissionAPI-key transport ceiling
listworkspace:read_environmentRead
getworkspace:read_environment_valuesAdmin
set, deleteworkspace:manage_environmentWrite

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.

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:

ToolResource area
steelengine_workspacesWorkspaces and membership
steelengine_workflowsWorkflow editing, execution, deployment, versions, and folders
steelengine_docsWorkspace documents and document folders
steelengine_tablesTables, databases, schemas, and rows
steelengine_appsDashboard apps, pages, widgets, versions, and publishing
steelengine_knowledgeKnowledge bases, documents, tags, and connectors
steelengine_jobsScheduled jobs and job logs
steelengine_envEnvironment variables and BYOK keys
steelengine_credentialsCredentials and OAuth authorization links
steelengine_mcp_serversWorkspace and workflow MCP connections
steelengine_skillsReusable workspace skills
steelengine_memoryAssistant memory
steelengine_logsExecution, workflow, job, and audit logs
steelengine_platformBlocks, triggers, tool search, documentation, and platform discovery
steelengine_a2aA2A 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 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, 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 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 for its narrower operation contract.

Errors

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

{
  "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:

{
  "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. 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.

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

No. SteelEngine MCP exposes platform operations for managing SteelEngine. Workflow MCP exposes workflows you deployed as callable MCP tools.
Yes. It is a compatibility alias for the same implementation. New clients should use /api/mcp/steelengine.
No. Claude.ai can use the OAuth flow. The signed-in user's current PBAC roles determine resource access.
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.
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.
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.

On this page