MCP server

Connect and identify the workspace

The hosted server URL is https://mcp.trydreamstate.com/mcp. OAuth is the first authentication choice, so no key is needed. Use a workspace machine key only for CI or a client without OAuth. The credential and principal are authenticated by the server rather than supplied in a tool input object.

After the client connects, call whoami before a capability request. It returns authenticated workspace and principal identity. This verifies the client is operating in the intended workspace and makes a wrong identity visible before it searches or runs work. A workspace boundary includes the actor, explicit scopes, and that workspace's spend policy.

Confirm my current workspace and explain the catalog-first flow for building a workbook.

The connection provides transport and identity. It does not select a pack, install a skill, or authorize a particular effect. Keep keys and bearer tokens out of prompts, repositories, and tool arguments. If an MCP client cannot use remote HTTP transport, use the CLI or direct REST instead of inventing a local server configuration.

The CLI needs Node.js 22 or newer. Run npm install -g @trydreamstate/cli, then dreamstate login. A successful login installs hosted Dreamstate skills for each detected Claude Code, Codex, or Cursor installation. Use dreamstate login --no-skills to skip skills, or dreamstate skills install --agents claude-code codex cursor --skill '*' to install them explicitly.

Route a goal and read skills

Use packs_list to read available pack definitions, packs_get to read one exact definition, and packs_route with a goal to select the work domain. Packs are metadata, not authority. A tables route helps an agent find workbook work, but it neither changes the MCP control roster nor bypasses the search and get steps.

Use skills_list to find workspace skills and skills_get to read one. Skills teach practice. They do not grant authority or bind a capability. For example, a workbook-building skill can explain the task sequence while the current tool contract still determines required inputs, available modes, cost policy, and output shape.

Route a workbook goal, read the list-building skill, then search for a current capability contract.

The MCP search control calls the scope field toolset. Architect uses pack_id for the equivalent scoped discovery field. These names are intentionally different by transport, so preserve the MCP spelling in an MCP request. No server URL parameter changes the toolset, and a pack scope applies only to the discovery request that carries it.

Search, get, then run

Every capability execution begins with tools_search. Search accepts a plain-language goal or query terms and can include a pack scope, output needs, input context, side-effect needs, a cursor, and a limit. The search response can include tool_turn_token and runnable_contracts. A contract marked fetched: true was delivered with the search response and can be run in that turn.

For any candidate not already fetched, call tools_get with the exact capability_id and the turn token. The get control can also read a batch through capability_ids, with a maximum of ten identifiers. It accepts compact or full detail. Compact is the model-facing form containing the input schema, required fields, modes, policies, and an example.

Call tools_run only after the contract is available. Pass its capability identifier, an object of parameters matching that schema, a current turn token, and an explicit mode when the capability mutates state. The run control supports smoke_test, dry_run, and live. The server never chooses live by default for a mutation.

Search for the contract that creates a workbook called Trial accounts. Use dry run and show the result before any live call.

A successful result uses the canonical envelope. It states whether the call was executed, its effect count and return kind, and can include data, changed values, a receipt, execution metadata, reversibility, and budget values. A state-bearing result can include a web_url for the matching app object. Use that deep link for a human view, but carry the JSON identifier for subsequent tool calls.

Inspect progress with runs

Use runs_list to page durable work, runs_get to inspect one run, runs_events to page its ordered event snapshots, and runs_cancel to request cancellation. Run list and events accept a cursor and a limit. The server returns next_cursor and has_more, so a client should pass the returned cursor back unchanged when another page exists.

A run read reports the durable run, state version, progress snapshots, partial results, exhaustion reason, retry frontier, degradation state, permitted operations, and timestamps. It also carries decision hints, a web URL, a UI URI, item counts, credit fields, terminal state, and failed-item repair hints. This HTTP get waits from zero through 20 seconds. An Architect streaming runs_get may wait up to 120 seconds in one call and returns as soon as the run is terminal. An unsettled response can be HTTP 202 with the same run id.

Inspect this run, page its events if needed, and show the current state version before taking a cancellation action.

Cancellation requires the state version from a prior read because the run may change between the read and the action. If a worker has moved it, read the new state and reconcile it. The full field and result-shape reference is on MCP reference.

When it goes wrong

If connection fails, confirm the hosted URL and OAuth sign-in. Use a workspace machine key only for CI or a client without OAuth, then call whoami after reconnecting. If the identity or workspace is wrong, stop and select the intended credential or workspace. The client should never place credentials in a tool input because the server authenticates them outside the MCP schema.

If a run returns capability_not_fetched, search again in the current turn, retain the new tool_turn_token, call get for the missing contract, and retry. If it returns mode_required, set one of the three documented modes. If a strict schema rejects a field, use the published field list rather than translating a CLI or REST spelling into MCP.

If a run control reports a changed state, call runs_get and use its latest state version. If a page says has_more: true, pass its cursor to the next request. If a live request returns quote_required, retain the same parameters and include the quote's credit ceiling when repeating it. For the error-envelope structure, see Envelope and errors.