# 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](/mcp).

## 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](/self-hosting/entra-workload-identities#exact-actions-and-minimum-grants)

| Tool                      | Resource                                                | Operations                                                                                                                                                          |
| ------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `steelengine_workspaces`  | Workspaces                                              | 9 ops including list, get, create, rename, update, member management                                                                                                |
| `steelengine_workflows`   | Workflows + workflow folders                            | 47 ops including block editing, run, deploy, version, clone/export/import, folder CRUD                                                                              |
| `steelengine_docs`        | Workspace docs + doc folders                            | 17 ops including read, write, patch, glob, search, folder CRUD                                                                                                      |
| `steelengine_tables`      | Workspace tables + databases                            | Human catalog: row CRUD, schema, column management, import and database grouping. Workload configuration is a separate closed subset with explicit archive cleanup. |
| `steelengine_apps`        | Apps (dashboard builder)                                | 15 ops including app/page CRUD, widget editing, validate, publish, rollback, versions                                                                               |
| `steelengine_knowledge`   | Knowledge bases                                         | 18 ops including KB CRUD, documents, tags, connectors                                                                                                               |
| `steelengine_jobs`        | Scheduled jobs                                          | 9 ops including create, pause, resume, logs                                                                                                                         |
| `steelengine_env`         | Environment variables + BYOK keys                       | 7 ops including list, get, set, delete, BYOK key management                                                                                                         |
| `steelengine_credentials` | OAuth credentials + API keys                            | 7 ops: create, update, list, auth\_link, rename, delete, generate\_api\_key                                                                                         |
| `steelengine_mcp_servers` | Workflow + external MCP servers                         | 8 ops                                                                                                                                                               |
| `steelengine_skills`      | Workspace skills                                        | list, add, edit, delete                                                                                                                                             |
| `steelengine_memory`      | Workspace memory                                        | list, search, add, correct, delete                                                                                                                                  |
| `steelengine_logs`        | Execution / workflow / job logs                         | execution\_summary, workflow\_logs, job\_logs, audit                                                                                                                |
| `steelengine_platform`    | Platform discovery (blocks, triggers, docs search, VFS) | 9 read-only ops                                                                                                                                                     |
| `steelengine_a2a`         | A2A agents                                              | 7 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

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

```bash
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

```bash
# 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.

```bash
cd apps/web

# Required environment:
export STEELENGINE_BASE_URL="https://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`:

```json
[
  {
    "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)

```bash
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](/blocks/human-in-the-loop#approval-methods) 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:

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

| Code                    | When                                                                                                                                                                                                             |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `invalid_params`        | Required 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_denied`     | The caller lacks the required catalog permission, an explicit deny applies, or the API-key scope cap excludes the target                                                                                         |
| `not_found`             | Targeted resource doesn't exist or is soft-deleted                                                                                                                                                               |
| `workspace_mismatch`    | Resource exists but belongs to a different workspace                                                                                                                                                             |
| `confirmation_required` | Destructive op called without `confirm: true`                                                                                                                                                                    |
| `duplicate_name`        | Auto-suffix retry cap exhausted on a folder/resource name                                                                                                                                                        |
| `cycle_detected`        | Folder move would create a parent-child cycle                                                                                                                                                                    |
| `unsupported_operation` | Operation name not recognized for this tool                                                                                                                                                                      |
| `tool_failed`           | Underlying server tool raised; original error in `error.details.output`                                                                                                                                          |
| `internal_error`        | Unexpected 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.
