@millwork/solver-mcp

@millwork/solver-mcp is the Millwork Solver execution MCP server. It gives an approved assistant 28 tenant-authenticated solver_* tools over stdio. Some tools read state. Others connect model sources, submit work, cancel a run, or decide a proposal, so the server is write-capable.

Install

Requires Node 20 or Node 22.

npm install @millwork/solver-mcp
solver-mcp --help

npm install @millwork/solver-mcp resolves the latest dist-tag. Pin an exact version for reproducible application builds.

Or run it directly:

npx --yes @millwork/solver-mcp --help

Connect an output check

Discover solver_list_verifiers first. An empty page without next_cursor returns a typed scaffold_output_check next action. Install @millwork/[email protected] or later to scaffold and test an output check locally, then deploy its HTTPS endpoint. The build-and-connect guide starts with Recipe 0 and shows the local test, deployment, and recovery path. Register a credential-less endpoint with solver_connect_verifier and retest with solver_test_verifier:

solver_connect_verifier({ access: "public", endpoint: "<https-url>",
  name: "<name>", version: "<version>", idempotency_key: "<caller-owned-id>" })

For a protected endpoint, connect with access: "managed", then use solver_start_verifier_connection to obtain the private browser handoff. Give its continue_url only to the intended person, and use solver_inspect_verifier_connection and solver_continue_verifier_connection to resume the same operation after private key entry. Never put the endpoint key in chat or a tool argument. Disconnecting requires separate host confirmation and confirm_disconnect: true; it stops Millwork's use of the key but does not revoke the key at the endpoint. Pass the returned verifier_id into solver_submit only after choosing the check. Connecting a check is not approval to run a task.

Configure stdio

Point the MCP client at the solver-mcp binary with no arguments. Supply these environment variables through the client's secret-aware environment configuration. Do not paste their values into a prompt, log, screenshot, or support report.

| Variable | Required | Meaning | |---|---:|---| | SOLVERAPI_API_KEY | yes | Tenant API key held by the server process and sent as bearer authentication. | | SOLVERAPI_BASE_URL | yes | API base including /v1; the production value is https://api.getmillwork.dev/v1. | | SOLVERAPI_MAX_RETRIES | no | Network/5xx retry limit. Default: 2. It never widens the safe retry boundary. | | SOLVERAPI_REFUSE_BASELINE_SUBMIT | no | When 1 or true, a live solver_submit without verifier_id is refused. Echo is not refused. Default: off. | | SOLVERAPI_RETRY_BACKOFF_MS | no | Exponential-backoff base in milliseconds. Default: 500. |

The transport contract is exact:

command: solver-mcp
arguments: none
transport: stdio
stdout: MCP JSON-RPC only
stderr: diagnostics

Use it with an assistant

Any MCP-capable assistant can use the same tool surface. Start with a read-only request:

Use solver_list_sources and solver_list_source_connections to show what this
organization can see. Do not call a tool that requires human confirmation.
Return tool names and safe counts only. Do not print credentials or customer
content.

For a write-capable request, make the stop explicit:

Prepare a solver_submit call but do not run it yet. Show the exact budget,
verifier, data classes, and caller-owned idempotency key. Wait for my explicit
confirmation before one call. If the outcome is uncertain, inspect status with
a read tool; do not submit again under a new key unless I confirm that new
intent.

Human confirmation is a client-side stop. The tenant API key still carries the server-side permissions assigned to it. Confirmation does not turn a tenant-wide machine key into a narrower credential.

A live solver_submit also requires the supported host-isolation profile. The host, not the prompt or launch environment, owns the fixed attestation, read-only admission ledger, and exact one-run approval channel. The first call can return host_approval_required; after the host writes the returned approval document to the named host-owned file, retry the exact same tool arguments and idempotency key. Echo submissions remain free and do not require this approval.

Tool surface

The server registers exactly 28 solver_* tools; tools/list over stdio is the authoritative surface, and every tool description states what the tool maps to and whether it writes. No tool ever accepts or returns raw credential material. Provider and protected-verifier setup use private browser handoffs; the tools return short-lived continuation URLs and opaque operation references, never raw keys.

Retry and recovery boundary

The 28 tools divide into:

• 13 safe reads that may retry network and 5xx failures;
• 7 same-key mutations, including solver_submit and solver_disconnect_verifier_connection, which may retry only with the same caller-owned, non-empty idempotency key and the same request bytes; and
• 8 write-capable tools that make one attempt because they expose no caller-owned idempotency key.

For those eight tools, a network or 5xx failure is a failure, not an automatic retry. The write might have applied before the response was lost. Inspect state with a safe read or your existing dashboard recovery path, then ask for explicit human intent before another write-capable tool call. Raising SOLVERAPI_MAX_RETRIES does not make those writes replay-safe.

Backend failures use RFC 7807. The MCP error result keeps the parsed Problem in structuredContent.problem; transport failures use network_error.

Support

Report problems on this repository's issue tracker. Useful evidence includes the tool name, retry boundary, attempt count, package and Node versions, and the Problem type, title, status, instance, and retry_after_s fields. Never include credentials or customer content: omit your tenant API key, your provider key/account details, authorization headers, task content, and tenant or resource identifiers.

Scope

This package is tenant-authenticated and write-capable. It is not a documentation-retrieval service and receives no tenant key from any other package. The Millwork documentation assistant is a separate, retrieval-only service with no execution authority.