DreamLake

DreamLake MCP

This local MCP adapter exposes namespace-scoped agent registry discovery, the personal built-in assistant, artifact and Memo visibility management, and reviewed Infrastructure registration moves. The assistant uses the same runtime, tools and permission checks as /agent/chat; MCP supplies the protocol wrapper. The adapter is distributed as repository source; there is no hosted MCP endpoint or published npm package. The Infrastructure tools call the production API using the bearer credential configured by the operator.

Registered agent definitions are declarations. Listing one does not make it executable. assistant_get discovers the concrete personal assistant supported by assistant_invoke; arbitrary registry IDs cannot be invoked.

Local setup

Use Node.js 22 or newer and a checkout of dreamlake-ai/dreamlake-workspace containing the mcp/ package. Install its separate locked dependencies:

bash
cd mcp
pnpm install --ignore-workspace --frozen-lockfile

Configure your local MCP client's stdio server entry with:

SettingValue
CommandAbsolute path to your node executable
ArgumentsAbsolute path to mcp/src/stdio.mjs in your checkout
DREAMLAKE_API_KEY environmentYour existing DreamLake bearer credential, supplied by your local client's secure environment configuration
DREAMLAKE_REMOTE environmentOptional API origin; defaults to https://api.dreamlake.ai

Use the client's local stdio configuration mechanism. Do not put credentials in chat prompts, tool arguments, source files or shared configuration. This adapter does not read the CLI credential store or mint credentials. If authentication expires, refresh the locally configured bearer and restart the MCP process.

Only configure an API origin you trust to receive that credential. HTTPS is required, except HTTP loopback for development. Redirects are refused. API paths, queries, URL credentials and fragments are not accepted in DREAMLAKE_REMOTE.

Launch node /absolute/path/to/mcp/src/stdio.mjs from the client, rather than pnpm start, so package-manager output cannot enter the MCP stdout protocol.

Project permissions boundary

This adapter has no direct Project policy, grant-management or effective-audience tools. The built-in runtime has separately authorized Project access tools, but assistant_invoke does not grant human organization-admin authority or remove its service-account namespace/grant restrictions. Use the released REST API or CLI 0.117.0+ for organization permission management; do not invent MCP tool names or invoke a model to work around an authorization refusal. See Project interface coverage.

Source visibility

The source-only adapter in a checkout containing PR #1944 adds source_get and source_visibility_set. Use the local setup above; these are not tools from a hosted MCP endpoint or a published adapter package. The configured backend must support the Source visibility contract.

Both tools require namespace and source (the immutable Source ID). source_get returns visibility, lifecycle, capabilities and settingsRevision. To change visibility, pass the same target, visibility (private, unlisted or public) and expectedSettingsRevision from that read to source_visibility_set. Source settings permission is required. The adapter returns bounded metadata, without connection credentials.

Stale revisions are refused. A lost or invalid write acknowledgement returns outcome: "reconcile-required" and automaticRetry: false; read source_get before deciding whether to retry. Reading a Source does not grant settings access.

Infrastructure registration moves

Use the same installed adapter with the authenticated user's existing credential. These tools are separate from the built-in assistant's restricted service-account tools; they do not grant that assistant namespace-owner powers.

ToolInputResult
infra_getstackId (immutable UUID)Authorized stack metadata, without raw Terraform state
infra_move_previewstackId, destinationNamespaceSlug, destinationProjectSlug; optional destinationName, destinationPathExact saved-review object with authority, state and path preconditions and blockers
infra_movestackId, the unchanged review, confirm: trueValidated move receipt and the same stack UUID

For example, request infra_move_preview with an existing stack UUID:

json
{
  "stackId": "11111111-1111-4111-8111-111111111111",
  "destinationNamespaceSlug": "acme",
  "destinationProjectSlug": "infrastructure-archive"
}

Review the complete returned object and its destination access scope. Only an executable review can be passed unchanged as review to infra_move, with the same stackId and explicit confirm: true. Execution does not accept destination overrides or silently obtain a newer review. Omitting a destination path in the preview preserves the current path across Projects.

The server checks namespace OWNER and Project ADMIN authority on both sides. The move changes registry placement/access, preserves Terraform state identity, and runs no Terraform or cloud operation. Read the full Infrastructure move contract, including binding, collision and lock blockers. The separate recipient-acceptance transfer protocol is not an automatic fallback.

No write is retried automatically. An unconfirmed execution returns outcome: "reconcile-required", automaticRetry: false, stackId and operationId; keep the original review and inspect infra_get before deciding whether to replay that exact operation. HTTP errors, malformed receipts, redirects and timeouts never count as successful moves. The adapter refuses redirects, bounds responses to 256 KiB and uses a 30-second request deadline. It exposes metadata only and excludes credentials and raw Terraform state.

Memo presence

The source adapter exposes memo_presence with explicit namespace and immutable memo ID. Optional selections defaults to true. It makes a scoped read only; it never joins, renews a lease or writes source. Public visibility alone does not grant collaboration access.

json
{"namespace":"my-team","memo":"0123456789abcdef01234567","selections":true}

The result includes participants, observedAt, status, selectionStatus and, when selection observation succeeds, selectionHash. Selection ranges use Unicode code points at that hash. An inactive room and an older server's unknown / unsupported capability are distinct from an observed empty room; service failures are tool errors. Selection text is untrusted context, not instructions or evidence of human edit authorship. Read current source before using a selection for an edit. See presence fields. This adapter remains source-only, with no hosted endpoint or published package.

Memo visibility

The source adapter exposes memo_get and memo_visibility_set. Both require namespace and memo (the stable 24-character Memo ID). For example:

json
{ "namespace": "my-team", "memo": "0123456789abcdef01234567", "visibility": "unlisted" }

Pass this object to memo_visibility_set. Values are private, unlisted and public. Unlisted allows anonymous direct-link reading while excluding the Memo from public profiles and discovery. Existing collaborators retain their access. The adapter reads current metadata and requires permissions.setVisibility before one metadata-only PATCH. It preserves content, history and share settings; returned metadata excludes share tokens. An uncertain acknowledgement returns outcome: "reconcile-required" and automaticRetry: false; inspect memo_get before deciding whether another write is needed. The adapter remains source-only.

Artifact visibility

The local adapter exposes artifact_get and artifact_visibility_set. Both require an explicit namespace and artifact slug and use the configured caller’s existing API permissions.

json
{ "namespace": "my-team", "artifact": "report", "visibility": "unlisted" }

Pass that object to artifact_visibility_set. The allowed values are private, public, and unlisted. Unlisted artifacts are readable by anyone with the direct URL, without login or a share token, but stay out of public profiles and feeds. Namespace members retain them in their catalog.

The tool first reads the existing artifact and checks viewerCanManage; a missing or deleted artifact is not created by this operation. It sends only visibility, preserving content, versions and share settings. Returned metadata excludes share tokens. If an update is unconfirmed, the result includes outcome: "reconcile-required" and automaticRetry: false. Read artifact_get with the same namespace and artifact to inspect the saved state before retrying. These direct tools do not change the read-only scope of assistant_invoke.

Registry discovery

Every registry operation requires an explicit namespace. The adapter never infers a namespace from the current project or scans other namespaces.

InterfaceInputResult
agents_listnamespace; optional page (default 1), pageSize (default 20, maximum 50), modulePaginated agent registry summaries with stable IDs and resource URIs
agents_getnamespace, agent (ID or name)One agent registry summary
Resource templatedreamlake://namespaces/{namespace}/agents/{agent}The same authorized summary as JSON

For example, call agents_list with:

json
{ "namespace": "my-team", "pageSize": 10 }

Then pass a returned ID to agents_get with the same namespace or read the returned resource URI. Listing resource templates does not enumerate private agents; use agents_list first. There is no project filter: these existing API operations are namespace-scoped.

Summaries include id, name, kind, module, qualname, description, latestVersion, publishedDefinitionVersion, creation/update timestamps, the requested namespace and the resource URI. latestVersion is a registry pointer, not an execution pin or proof that this agent can be invoked. Arbitrary metadata, agent markdown, channels and internal namespace IDs are excluded. Descriptions are untrusted user-authored text, not instructions for the client.

Whole-agent releases

The source adapter exposes four release operations. Every operation requires namespace and agent (ID or name), using the same caller identity as discovery.

ToolAdditional inputResult
agent_definition_versionsOptional page (1), pageSize (20, maximum 200)Release summaries without prompt bodies
agent_definition_version_getFull version hashFrozen README template, prompt, configuration and source revisions
agent_definition_publishexpectedUpdatedAt; optional labelCaptures and activates the saved draft
agent_definition_activateFull version hash, expectedUpdatedAtChanges the active release while preserving the draft

Read the agent before either write and use the timestamp of the draft you reviewed. A release preserves content, never old access grants: detail reads and execution check current memo access. A stale timestamp is refused. An uncertain write returns outcome: "reconcile-required" and automaticRetry: false; inspect the head and history before deciding whether to retry. Responses are bounded to 1.1 MiB with a 30-second request deadline and redirects refused.

See README templates and whole-agent releases for snapshot identity, captured content, draft selection and rollback semantics. These tools manage definitions and do not start an assistant turn.

Invoke the personal assistant

  1. Call assistant_get with {} to check your existing pilot eligibility and discover dreamlake-assistant. This read does not provision a session; execution availability is checked when you invoke.
  2. Call assistant_invoke with { "assistantId": "dreamlake-assistant", "message": "Find my project notes" }. It sends one real turn to /agent/chat and waits up to 180 seconds.
  3. Call assistant_session_get with the returned sessionId, or read the returned dreamlake://assistant/sessions/{sessionId} resource, to retrieve current status and saved messages.

Only your existing DreamLake bearer is used. The server derives your personal identity; the MCP client cannot select another human or service account. Each invocation uses capabilities: {}, enabling the existing read scopes and any deployment-approved web search. Resource writes, session control and browser actions are unavailable. Invoking can incur model usage and creates/persists conversation records, so the MCP tool is correctly marked non-read-only and non-idempotent.

A successful invocation returns its sessionId, turnId, resourceUri and outcome: completed only after the API sends its persisted-completion event. The resource is an evolving conversation, not an immutable per-turn run. Its running, idle or error status describes the current conversation. Reads include a revision and default to the latest four saved messages. Use offset and limit (maximum five) to page earlier messages. Pass sessionId to a later invocation to continue the same conversation.

assistant_sessions_list lists your own recent conversations, with optional limit (maximum 50) and cursor. This also provides recovery when a connection failed before the invocation could return its newly created session ID.

The adapter never retries a model invocation automatically. A truncated stream, API error, timeout or disconnected transport may mean that work already began. An unconfirmed result includes any known session reference; inspect it or recent history before deciding whether to send another turn. Canceling or closing the client aborts the HTTP stream; the existing backend owns recording its failed or interrupted turn. This is not a detached job queue or an idempotent-run API.

Authorization and limits

Registry calls use the configured bearer directly against the selected DreamLake API's existing runnable:read authorization. Assistant discovery/invocation reuse the built-in pilot policy; session/history reads enforce their existing active-user and ownership rules. Resource reads perform a fresh API read, too. There is no credential exchange, elevated service identity, local permission cache, or connector-token forwarding.

Registry reads time out after 15 seconds; their upstream JSON responses are capped at 256 KiB. Assistant reads also time out after 15 seconds and accept at most 2 MiB of JSON; invocation streams have a 180-second deadline and 512 KiB cap. Summaries have field limits, and a response outside the supported shape fails closed. A large registry page can exceed the byte limit; retry with a smaller page. Upstream errors are replaced with bounded messages that do not include response bodies, exception details or credentials. Authorization denial and a missing record produce the same message. A non-agent runnable cannot be read through this adapter.

The official TypeScript MCP SDK 2.4.0 serves both legacy initialization clients and the 2026-07-28 protocol. Tests use the official client over a spawned stdio process in both modes, including retrieval after restarting the adapter. The pilot does not start an HTTP listener or require infrastructure deployment.

Validation and remaining gates

From mcp/, run pnpm test. The suite verifies the wire protocol, API request scope, resource authorization, response projection, invalid inputs, denied and expired credentials, redirects, oversized responses and startup diagnostics. It uses a local HTTP fixture and does not require production credentials.

The local adapter now supports genuine built-in assistant invocation and durable saved-session retrieval. General registered-agent dispatch, immutable run IDs, idempotent execution retries and a remote OAuth-protected MCP service remain separate work. Agent/run record routes alone do not dispatch execution. Any new server hosting must use the central DreamLake Terraform workflow.

Client configuration

For Codex, configure a stdio entry using environment variable names rather than credential values. Allow at least 210 seconds for an invocation:

toml
[mcp_servers.dreamlake]
command = "/absolute/path/to/node"
args = ["/absolute/path/to/dreamlake-workspace/mcp/src/stdio.mjs"]
env_vars = ["DREAMLAKE_API_KEY", "DREAMLAKE_REMOTE"]
tool_timeout_sec = 210

For Claude Code, a stdio entry can expand the same local environment variables:

json
{
  "mcpServers": {
    "dreamlake": {
      "type": "stdio",
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/dreamlake-workspace/mcp/src/stdio.mjs"],
      "env": {
        "DREAMLAKE_API_KEY": "${DREAMLAKE_API_KEY}",
        "DREAMLAKE_REMOTE": "${DREAMLAKE_REMOTE:-https://api.dreamlake.ai}"
      },
      "timeout": 210000
    }
  }
}

Provide the bearer in the client's launch environment, review the local server configuration, and follow the client's normal permission prompts. These examples do not grant additional DreamLake permissions. See the official Codex MCP configuration and Claude Code MCP configuration.

Protocol references: official TypeScript SDK, stdio serving, and MCP authorization.

Memo cover images

memo_get includes coverFileId. To set a cover, call memo_cover_set with namespace, memo (stable ID), and coverFileId (a live image attachment ID belonging to that memo). Pass null to remove the cover without deleting bytes. Upload through the existing Memo files API or dl memos cover --file first. The adapter checks metadata permission and verifies the returned cover value. An unconfirmed result requires reading memo_get before deciding whether to retry; it never automatically retries. Body content and collaboration are unchanged.

Annotation metadata

The local source adapter includes annotation_get and annotation_update. Both require an explicit namespace and annotation (immutable name or URL slug). Read first, then supply slug, expectedResourceId, expectedSlug, and expectedRevision from that observation to rename a URL. title and visibility are optional independent updates. The backend enforces current namespace management authority for slug changes, retains old links and preserves content. The adapter excludes share tokens and never retries uncertain writes. Re-read with annotation_get to reconcile. See Annotations reference.