MCP reference
Review the controls exposed by the Dreamstate MCP server.
The Dreamstate MCP server has thirteen shared controls: six metadata controls, three capability controls, and four run controls. Use this reference when an MCP client must send exact field names and limits instead of guessing from a workflow. The server at https://mcp.trydreamstate.com/mcp is the same contract used by Architect, the CLI, and the REST API.
The controls are intentionally small. A pack and a skill describe and route work, while a capability contract determines the input, execution policy, and output for the work itself. Call tools_search, keep the returned turn token, call tools_get for any contract not delivered as runnable, then call tools_run. See MCP server for connection and turn-flow guidance.
Connect to the MCP server
Use https://mcp.trydreamstate.com/mcp for every MCP client. OAuth is first, so no key is needed. Use a workspace machine key only for CI or a client without OAuth, with Authorization: Bearer <machine key>.
Read controls declare readOnlyHint, so they do not need confirmation. Write controls declare their own annotations. ChatGPT confirms write actions.
Identity, packs, and skills
Metadata controls are strict objects. whoami and packs_list accept an empty object. packs_get needs the exact pack_id, while packs_route needs a non-empty goal. A pack is metadata rather than authority. Routing a goal to the tables pack does not alter the MCP tool list or make a capability safe to call without its contract.
Skills are also metadata. skills_list accepts a query and a numeric limit from 1 through 10. skills_get requires the skill identifier and can select a supporting file. Read a skill for practice, then use the capability controls for the action. The server authenticates the credential and principal, so neither is a field in these tool inputs.
| Control | Arguments | Result |
|---|---|---|
whoami | None | Authenticated workspace and principal identity. |
packs_list | None | Available capability-pack definitions. |
packs_get | pack_id: string, required | One pack definition. |
packs_route | goal: non-empty string, required | The pack route for a goal. |
skills_list | query: string, optional; limit: integer 1 to 10, optional | Workspace skill metadata. |
skills_get | id: non-empty string, required; file: non-empty string, optional | One skill or a selected supporting file. |
Identify my workspace, route a workbook goal, then show the list-building skill before searching for a capability.The example returns metadata rather than a workbook. That separation is useful: the client can show the intended workspace and relevant practice before it prepares an execution request. If a skill has a supporting file, pass its exact relative file value to skills_get. Do not invent an input that resembles a capability identifier, because each metadata schema rejects unrecognized keys.
Search, get, and run
tools_search requires a goal, query terms, or both. Its limit accepts 1 through 50 and the HTTP route builds a default limit of 25 when one is omitted. Search can scope discovery to one pack through toolset. This is a discovery filter, not a persistent MCP server setting. The same pack field is called pack_id by Architect, but MCP uses toolset for search.
tools_get needs exactly one identifier form. Use capability_id for one record or capability_ids for a batch of up to ten. Supplying both forms or neither is invalid. The compact detail is the normal model-facing contract: inputs, required fields, modes, policies, and an example. Full detail asks for the whole catalog record.
tools_run uses the fetched capability identifier and an object of capability parameters. Its params default is an empty object, but that is not a substitute for required fields in the underlying schema. A mutation must name a mode. The route returns mode_required when mode is absent and names smoke_test, dry_run, and live as repairs.
| Field | Required | Meaning | Default |
|---|---|---|---|
tools_search.goal | Goal or query_terms | A non-empty goal, maximum 2,000 characters. | None |
tools_search.query_terms | Goal or query_terms | One to 50 non-empty search terms. A comma-separated REST value becomes terms. | None |
tools_search.version | Optional | Contract version. Only 1 is accepted. | Omitted |
tools_search.domains | Optional | Up to 50 domain terms used to narrow discovery. | Omitted |
tools_search.kinds | Optional | Up to 20 search kinds from the published kind enum. | Omitted |
tools_search.available_inputs | Optional | Up to 50 input terms already available to the caller. | Omitted |
tools_search.desired_outputs | Optional | Up to 50 output terms the caller needs. | Omitted |
tools_search.required_side_effects | Optional | Up to 50 effect terms that the work must include. | Omitted |
tools_search.excluded_side_effects | Optional | Up to 50 effect terms that the work must avoid. | Omitted |
tools_search.toolset | Optional | One pack identifier that scopes discovery. MCP uses toolset here. | Omitted |
tools_search.tool_turn_token | Optional | A token returned by an earlier search in the same turn. | Omitted |
tools_search.agent_session_id | Optional | A UUID identifying an agent session. | Omitted |
tools_search.table_action_mode | Optional | Either source or column for table-action suggestions. | Omitted |
tools_search.cursor | Optional | A non-empty cursor returned by a previous search page. | Omitted |
tools_search.limit | Optional | An integer from 1 through 50. | Server search defaults to 25 |
tools_get.capability_id | Exactly one id form | One exact capability identifier, maximum 240 characters. | None |
tools_get.capability_ids | Exactly one id form | A batch of 1 through 10 exact capability identifiers. | None |
tools_get.workspace_id | Optional | A workspace UUID. | Omitted |
tools_get.tool_turn_token | Optional | The token from the current discovery turn. | Omitted |
tools_get.agent_session_id | Optional | A UUID identifying an agent session. | Omitted |
tools_get.detail | Optional | compact returns contract information; full requests the full catalog record. | compact |
tools_run.capability_id | Required | One exact capability identifier, maximum 240 characters. | None |
tools_run.params | Optional | An object that must match the fetched capability input schema. | Empty object |
tools_run.mode | Capability dependent | smoke_test, dry_run, or live. A mutating call with no mode is refused. | Read behavior depends on the capability |
tools_run.max_credits | Optional | A non-negative credit ceiling for the execution envelope. | Omitted |
tools_run.quote_hash | Optional | The quote hash returned by a priced earlier call. | Omitted |
tools_run.tool_turn_token | Optional | The current discovery-turn token. | Omitted |
tools_run.idempotency_key | Live write dependent | A replay-safety key. The server requires it only when the live write needs it. | Omitted |
tools_run.agent_session_id | Optional | A UUID identifying an agent session. | Omitted |
tools_run.workflow_id | Optional | A workflow UUID. | Omitted |
Find the contract for creating a workbook called Trial accounts. Use dry run and show the returned state before a live call.A successful canonical execution envelope can contain ok, executed, effect_count, returns, data, changed, receipt, meta, reversibility, and budget fields. The execution metadata contains a capability identifier plus nullable run, idempotency, and grant-evaluation identifiers. A state-bearing result can also provide a web_url in its published response so a person can open the result in the web app.
For a priced live call, use the quote returned by the server and keep the same parameters when repeating the call with a non-negative max_credits value. A quote hash is a transport field beside params, not a capability parameter. For a live write that needs replay safety, send idempotency_key at the top level. A dry run and a smoke test never need that write-specific key.
Inspect and control runs
Run controls operate on durable work after a capability returns a run identifier. runs_list is paged with a cursor and a limit. Its result has runs, next_cursor, and has_more. Each listed run includes its identifier, capability or run kind, status, and start time. Pass the returned cursor back unchanged rather than constructing one.
runs_get includes a required path-style run_id and optionally waits for zero through 20 seconds on this HTTP call. An Architect streaming runs_get may wait up to 120 seconds and returns as soon as the run is terminal. Omit wait_seconds for an immediate snapshot; a zero also requests no wait. An unsettled run can return HTTP 202 with the same run identifier. The response exposes the durable run, next decision hints, item counts, credit estimates and actuals, terminal state, and failed items.
runs_events adds an ordered event page to the run read. runs_cancel requires the last observed expected_state_version. Read the run first, then provide its state version so the server can reject a cancellation that races with a changed run. A reason is optional and is limited to 1,000 characters. Version is constrained to 1 and defaults to 1.
| Control | Arguments | Result shape |
|---|---|---|
runs_list | cursor: string or null, optional; limit: integer 1 to 500, default 100 | runs, next_cursor, has_more |
runs_get | run_id: non-empty string, required; wait_seconds: integer 0 to 20 on this HTTP call (Architect streaming runs_get accepts 0 to 120), optional | run, decision hints, item counts, cost fields, terminal state, failed items |
runs_events | run_id: non-empty string, required; cursor: string or null, optional; limit: integer 1 to 500, default 100 | runs_get result plus ordered events |
runs_cancel | run_id: non-empty string, required; version: 1, default 1; expected_state_version: non-negative integer, required; reason: string up to 1,000 characters, optional | Updated run resource |
Inspect my latest run. If it is still active, show its events. If it has failed, show the exact repair hint before taking another action.The durable run includes run_id, run_kind, status, state_version, completed and incomplete steps, partial results, paging values, an exhaustion reason, retry frontier, degradation information, and permitted run operations. It also includes creation and update timestamps. The run-read result adds a web URL and UI URI, plus a decision hint and its kind. Treat these fields as the current state, not as a promise that the next worker transition will succeed.
When it goes wrong
A malformed MCP input is rejected by the strict published schema. For a search, provide a goal or query terms. For a get, provide exactly one of capability_id and capability_ids. For a run, correct the input to the published schema and retry. The REST implementation returns invalid_request for invalid inputs and includes a repair whose kind is fix_input.
If the gateway answers capability_not_fetched, start over with search in the current client turn. Keep its tool_turn_token, use get for the missing contract, then retry the same capability. Do not reuse a token from an unrelated conversation turn. If the gateway answers mode_required, choose the required mode deliberately rather than relying on a live default.
If a cancellation fails because the run changed, call runs_get again and use the new state_version. If a list or events response has has_more: true, call the same control with its next_cursor. If the response reports provider degradation, use its retry information and decision hint instead of launching a duplicate request. For a priced call that returns quote_required, preserve the quoted request parameters and add a credit ceiling when repeating it.