MCP Server Production Readiness

Validation checklist for SteelEngine's MCP server — what to run before shipping changes that touch the LLM-facing surface.

SteelEngine exposes its own MCP server at /api/mcp/steelengine (consumed by Claude Desktop, Cursor, and any external MCP client). This page is the checklist for verifying that surface is production-ready after changes. The legacy /api/mcp/copilot route remains available as a compatibility alias.

This is the server-side readiness check. For configuring MCP clients (external tools you connect to SteelEngine), see Using MCP Tools.

What the MCP server can expose

tools/list is principal-specific. The table below is the complete server catalog, not a promise that every authenticated client receives every tool or operation. Discovery can prune operation enums and oneOf branches, and omits a tool when no operation remains visible.

Entra workload callers discover their permitted workspace, workflow, logical database and table, environment, KB, paused OAuth connector, and workspace BYOK operations through tools/list. The workload action matrix includes retained deployment graph lookup under workflow:read and separate grants for resource configuration and cleanup. Connector creation starts paused. Update authority can pause idle connectors, and activation remains human-authorized. Workspace provider keys stay write-only, with revision checks, retry validation, and organization fallback. Validate federation, scoped grants and exclusions, worker revocation, Key Vault access, and token renewal in the target environment. Workload action matrix

ToolResourceOperations
steelengine_workspacesWorkspaces9 ops including list, get, create, rename, update, member management
steelengine_workflowsWorkflows + workflow folders47 ops including block editing, run, deploy, version, clone/export/import, folder CRUD
steelengine_docsWorkspace docs + doc folders17 ops including read, write, patch, glob, search, folder CRUD
steelengine_tablesWorkspace tables + databasesHuman catalog: row CRUD, schema, column management, import and database grouping. Workload configuration is a separate closed subset with explicit archive cleanup.
steelengine_appsApps (dashboard builder)15 ops including app/page CRUD, widget editing, validate, publish, rollback, versions
steelengine_knowledgeKnowledge bases18 ops including KB CRUD, documents, tags, connectors
steelengine_jobsScheduled jobs9 ops including create, pause, resume, logs
steelengine_envEnvironment variables + BYOK keys7 ops including list, get, set, delete, BYOK key management
steelengine_credentialsOAuth credentials + API keys7 ops: create, update, list, auth_link, rename, delete, generate_api_key
steelengine_mcp_serversWorkflow + external MCP servers8 ops
steelengine_skillsWorkspace skillslist, add, edit, delete
steelengine_memoryWorkspace memorylist, search, add, correct, delete
steelengine_logsExecution / workflow / job logsexecution_summary, workflow_logs, job_logs, audit
steelengine_platformPlatform discovery (blocks, triggers, docs search, VFS)9 read-only ops
steelengine_a2aA2A agents7 ops including list, get, create, update, publish/unpublish

The server advertises domain tools only. Interactive delegation tools and Chat's integration search/run tools are not part of the public MCP contract. External clients can create a scheduled prompt task through steelengine_jobs.create; it appears as a Sub Agent and executes later in the Temporal Worker.

Pre-ship checklist

1. Type check passes

bun run type-check

Run this from the repository root. TypeScript catches renamed types, missing imports, and schema/handler drift across the affected packages. The external HTTP routes remain in apps/web/app/api/mcp/. The shared catalog, gateway, PBAC, and domain plans live in packages/platform-tools/src/lib/platform-tools/; protocol helpers live in packages/mcp. Chat and scheduled Sub Agents use packages/assistant-runtime to call the shared gateway directly.

2. PBAC contract tests pass

Run the exact-authorization and discovery tests first:

cd apps/web && bunx vitest run \
  lib/platform-tools/pbac.test.ts \
  lib/platform-tools/tool-discovery.test.ts \
  app/api/mcp/copilot/route.test.ts

These tests must prove:

  • Catalog permission metadata resolves to the correct object and action.
  • tools/list prunes both the operation enum and discriminated oneOf branches.
  • A tool with zero visible operations is omitted.
  • tools/call re-authorizes a hidden or stale operation.
  • API-key scope is applied after owner PBAC authorization as a second cap.
  • A denial includes the catalog permission key and target when exact mapping is available.

3. Unit + integration tests pass

# MCP definitions and tool-id aliases
cd apps/web && bunx vitest run ./lib/platform-tools/catalog/definitions.test.ts \
                               ./lib/copilot/tools/tool-id-aliases.test.ts

# Routes, hooks, services
cd apps/web && bunx vitest run \
  lib/copilot/ \
  lib/folders/ \
  app/api/mcp/ \
  app/api/v1/ \
  app/api/workspaces/ \
  app/api/files/ \
  app/api/chat/ \
  hooks/queries/

All test files in this repository are Vitest files. A bare bun test invokes Bun's own runner and does not load the Vitest setup. Expected: every test passes.

4. End-to-end certification harness against a live deployment

mcp-certify.ts is the production gate. It calls every tool, every operation, against a real workspace and validates response envelopes, error codes, confirmation gates, and structured output contracts.

cd apps/web

# Required environment:
export STEELENGINE_BASE_URL="https://dev.steelengine.com"   # or staging
export STEELENGINE_MCP_API_KEY="sk-steelengine-..."        # SteelEngine MCP key
export STEELENGINE_ORGANIZATION_ID="org_..."                # required for workspace-create probes
# Optional:
export STEELENGINE_WORKSPACE_ID="wsp_..."                  # reuse existing workspace
export STEELENGINE_OAUTH_BEARER_TOKEN="..."                # if testing bearer auth path

bun run mcp:certify

To run the restricted-role gate, set STEELENGINE_MCP_PBAC_FIXTURES to a JSON array of pre-provisioned API-key fixtures. The harness requires scenarios named custom_role, group_assignment, explicit_deny, role_inheritance, organization_scope, workspace_scope, and api_key_scope. Each fixture can assert visible operations, hidden operations, and direct calls that must return permission_denied:

[
  {
    "name": "document reader with explicit table deny",
    "scenario": "explicit_deny",
    "apiKey": "sk-steelengine-...",
    "visible": [{ "tool": "steelengine_docs", "operation": "read" }],
    "hidden": [{ "tool": "steelengine_tables", "operation": "query_rows" }],
    "deniedCalls": [
      {
        "tool": "steelengine_tables",
        "args": { "operation": "query_rows", "tableId": "tbl_..." }
      }
    ]
  }
]

Provide at least one fixture for every required scenario in the complete array. This makes the live gate verify the actual persisted role, group, inheritance, deny, assignment-scope, and API-key configuration instead of only simulating those decisions in unit tests.

The harness exercises (in order):

  • Auth: unauthenticated requests rejected; invalid API key rejected; optional bearer-token auth
  • tools/list public contract
  • Workspace CRUD via steelengine_workspaces
  • All domain operation envelopes
  • Workflows + workflow folders
  • Docs + doc folders (including create_folder, rename_folder, move_folder, delete_folder cascade)
  • Tables
  • Knowledge bases
  • Jobs
  • Environment + credentials
  • MCP servers (workflow + external)
  • Skills + memory
  • Logs + platform discovery
  • Credential OAuth link generation through steelengine_credentials.auth_link
  • Response envelope + redaction invariants
  • Restricted custom-role fixtures: read-only discovery, create-without-update, group-derived access, explicit deny, workspace scope, and API-key scope intersection

Harness runs authenticate with STEELENGINE_MCP_API_KEY (the legacy copilot key variable is no longer read by the scripts).

5. Smoke test (lighter weight)

cd apps/web && bun run mcp:smoke

The smoke harness runs a single happy-path call against each tool. Useful for fast verification after small changes; not a replacement for the cert harness.

Production-readiness criteria

The MCP server is production-ready when:

  • Every domain tool has a rich description (when-to-use, when-not, ops, errors, examples, side effects) - see packages/platform-tools/src/lib/platform-tools/catalog/domain-tools.ts
  • Every domain tool has per-op discriminated JSON Schema (oneOf branches keyed on operation) - see packages/platform-tools/src/lib/platform-tools/catalog/per-op-schemas.ts
  • apps/web/lib/platform-tools/catalog/schema-contract.test.ts passes: every argument an operation's executor reads is published in its schema or listed with a reason in catalog/unpublished-args.ts, and every renamed argument in DOMAIN_ARGUMENT_ALIASES maps to a published name
  • Every advertised operation declares one or more Permission Catalog requirements; no domain relies on the compatibility read/write/admin capability projection
  • Every catalog requirement resolves its target only after the execution plan has resolved workspace and resource ownership
  • tools/list filters operations from owner PBAC plus API-key scope and omits empty tools
  • tools/call performs the same exact check again and does not trust discovery
  • Custom-role, group, org-wide, workspace-scoped, inheritance, and explicit-deny cases are certified
  • Every destructive operation requires confirm: true and returns confirmation_required when missing
  • Ordinary human/tool/API-key paths reject database deletion; dashboard and separately granted workload configuration permit archival only for an empty database. Workload cleanup also checks exact target/revision, confirmation, retry identity, current scope and managed-resource restrictions.
  • Workload table configuration excludes row access, SQL and destructive schema changes; cleanup rejects relationship dependencies, retains owned rows, and commits physical DDL, audit and retry receipt atomically.
  • Chat and scheduled assistants use direct gateway calls with current authorization, JSON-serializable results, and no internal MCP HTTP request
  • Denying a Chat approval ends tool execution for that response; the assistant does not retry the same action with different arguments
  • steelengine_workflows.resume_paused rejects a mismatched workflow, execution, or pause context, including when the client supplies contextId explicitly
  • Approval summaries omit the execution snapshot; decisions record the authenticated user and, for MCP API-key calls, the key that submitted them
  • Every response is a structured envelope: {success, message?, data?, error?}
  • steelengine_credentials.auth_link returns structured OAuth URL data
  • No legacy steelengine_files references in tool descriptions or prompts
  • No legacy 'workspace_file' etc. canonical tool IDs (alias map handles historical chat replay)
  • Folder ops live on the parent resource tool (steelengine_docs.{,*}_folder, steelengine_workflows.{,*}_folder)
  • Public REST /api/v1/docs and /api/v1/docs/folders match MCP semantics
  • OpenAPI spec documents folderId on all relevant ops + DocMetadata.folderId
  • Audit log writes on every folder mutation (create, update, delete) regardless of surface
  • Environment list, get, and set independently enforce metadata, reveal, and write permissions; workload identities cannot retrieve values
  • Environment failures omit raw exception details, responses prevent HTTP caching, and successful value reads emit best-effort audits without values
  • Workload KB configuration schemas match dispatch validation; create/update/delete retries reauthorize actual parents and keep resource writes, success audits, and safe receipts atomic
  • KB configuration grants do not expose document content, ingestion/search, connector configuration, or sync, and deletion preserves the canonical archival/pause lifecycle
  • Workload connector pausing requires update authority and exact revision/retry checks; it grants no credential use or activation, conflicts with running syncs, and prevents queued automatic syncs from overriding a pause

All of these must be enforced by the unit tests, the cert harness, or both. Exact PBAC metadata and call enforcement cover the complete domain and direct-tool catalog; changes must keep the zero-legacy-metadata grep gates and restricted-role certification green.

When something fails

  • Type check fails → fix the type error. Don't ship.
  • Unit test fails (new failure) → fix. Pre-existing failures on main are tracked but don't block.
  • Cert harness fails on a domain tool → that tool has a regression. The harness output tells you which operation. Check packages/platform-tools/src/lib/platform-tools/gateway.ts and its domain plan for that operation. The MCP routes adapt external requests to that gateway.
  • Cert harness fails on response envelope (returned success=true without message or data) → the response builder for that operation forgot to set message or data. Common when extending a tool.
  • Cert harness fails on credential OAuth link shape → the credentials domain plan or OAuth URL extraction changed. Check packages/platform-tools/src/lib/platform-tools/domain-plans/credentials.ts and packages/platform-tools/src/lib/copilot/orchestrator/tool-executor/oauth-links.ts.

Building production-ready workflows + agents via MCP

The tool surface is intentionally designed so an LLM client can construct a full SteelEngine application without falling through to natural-language subagents:

  1. Discover the workspace → steelengine_platform.blocks to learn block types, steelengine_platform.triggers for trigger types, steelengine_platform.tool_search to discover integration tools by regex.
  2. Set up infrastructure → steelengine_credentials.auth_link to OAuth-connect external services; steelengine_env.set for API keys; steelengine_knowledge.create for KBs.
  3. Build workflows → steelengine_workflows.create_folder to organize, steelengine_workflows.create to make a workflow, then steelengine_workflows.edit_blocks for canvas edits.
  4. Iterate → steelengine_workflows.run / run_until_block / run_from_block for partial execution; steelengine_workflows.get_logs for execution logs.
  5. Deploy → steelengine_workflows.deploy_api, deploy_chat, or deploy_mcp (all destructive + confirm-gated).
  6. Manage runtime artifacts → steelengine_docs.{write,read,patch} for prompts/configs/outputs; steelengine_tables.{insert_row,query_rows} for structured data; steelengine_jobs.create for scheduled runs.

MCP provides these operations to external agents and clients. Internal Chat and scheduled Sub Agents share their domain handlers and authorization through the platform tool gateway. Availability can differ by surface; a dashboard control does not imply a corresponding MCP operation.

Human approval resumes

Use steelengine_workflows.list_paused with workflowId to discover paused executions and their pausePoints. Resume with resume_paused, the same workflowId, the chosen executionId, and the pause point's contextId. If contextId is omitted, the server selects the first active pause point; supply it explicitly when several approvals are pending. The server checks that the workflow, execution, and context belong together even when all three IDs are supplied.

Pass form values in input. A plain resume defaults to approval; to deny, set input._humanInTheLoopDecision to "denied" and optionally include input.rejectionReason. See Human in the Loop for decision behavior. The server records the authenticated user and API-key identity, rather than accepting a decision-maker identity from tool arguments. Paused-execution summaries expose pause details without returning the saved execution snapshot; inspect recorded decisions in the in-app approval review. A successful resume returns a receipt with status, resumeExecutionId, and contextId; it does not mean the workflow has finished.

Capabilities the server advertises

The MCP server advertises only the tools primitive in its initialize response:

{ "capabilities": { "tools": {} } }

resources and prompts are not advertised today. This is intentional:

  • Tools are the right primitive for SteelEngine's API surface — every operation is an action the LLM can take.
  • Resources would let MCP clients reference docs/tables as MCP-native URIs. Not currently needed because every doc and table is already addressable via steelengine_docs and steelengine_tables tools. Adding resources would create two ways to do the same thing.
  • Prompts would expose canned prompt templates. Not currently needed because the LLM-facing prompt-building happens client-side.

If a future use case requires either, both can be added without breaking existing tools/* callers.

Idempotency and replay

The MCP server does not implement a general idempotency key for tool calls. Repeating tools/call can execute the operation again. Some updates are naturally idempotent, such as setting a value to its existing value. Creation or external side effects may repeat. Auto-suffixing a duplicate name creates another resource; confirm: true confirms intent but does not deduplicate a call.

If a write times out or returns an ambiguous failure, inspect its outcome through the equivalent list, get, or logs operation before retrying. Backoff controls retry rate; it does not prevent duplicate effects. Apply the same care when manually restarting an interrupted scheduled Sub Agent.

Error code reference

The MCP server emits these structured error codes via error.code on failed envelopes:

CodeWhen
invalid_paramsRequired field missing, fails JSON Schema validation, or an argument name is a probable misspelling of one the operation reads (other unknown names are removed before the call runs and reported in warnings)
permission_deniedThe caller lacks the required catalog permission, an explicit deny applies, or the API-key scope cap excludes the target
not_foundTargeted resource doesn't exist or is soft-deleted
workspace_mismatchResource exists but belongs to a different workspace
confirmation_requiredDestructive op called without confirm: true
duplicate_nameAuto-suffix retry cap exhausted on a folder/resource name
cycle_detectedFolder move would create a parent-child cycle
unsupported_operationOperation name not recognized for this tool
tool_failedUnderlying server tool raised; original error in error.details.output
internal_errorUnexpected error; check logs

Tool descriptions reference these by name in their ERRORS: section. One exception is the ambiguous_table_name case named in the steelengine_tables description (a tableName that matches several tables). The server returns it as invalid_params. The message begins ambiguous_table_name: and lists the matching table IDs. Errors from the underlying tool layer (e.g. embedding failures, OAuth misconfiguration, storage quota) are surfaced as tool_failed with the original message in error.details.output rather than getting their own top-level codes — keeps the public contract small.

Environment operation exceptions use a generic internal_error message, Environment operation failed. Their logs omit the exception so a parser or storage failure cannot echo secret input through the error envelope or logger.

On this page