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:
Configure your local MCP client's stdio server entry with:
| Setting | Value |
|---|---|
| Command | Absolute path to your node executable |
| Arguments | Absolute path to mcp/src/stdio.mjs in your checkout |
DREAMLAKE_API_KEY environment | Your existing DreamLake bearer credential, supplied by your local client's secure environment configuration |
DREAMLAKE_REMOTE environment | Optional 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.
| Tool | Input | Result |
|---|---|---|
infra_get | stackId (immutable UUID) | Authorized stack metadata, without raw Terraform state |
infra_move_preview | stackId, destinationNamespaceSlug, destinationProjectSlug; optional destinationName, destinationPath | Exact saved-review object with authority, state and path preconditions and blockers |
infra_move | stackId, the unchanged review, confirm: true | Validated move receipt and the same stack UUID |
For example, request infra_move_preview with an existing stack UUID:
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.
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:
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.
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.
| Interface | Input | Result |
|---|---|---|
agents_list | namespace; optional page (default 1), pageSize (default 20, maximum 50), module | Paginated agent registry summaries with stable IDs and resource URIs |
agents_get | namespace, agent (ID or name) | One agent registry summary |
| Resource template | dreamlake://namespaces/{namespace}/agents/{agent} | The same authorized summary as JSON |
For example, call agents_list with:
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.
| Tool | Additional input | Result |
|---|---|---|
agent_definition_versions | Optional page (1), pageSize (20, maximum 200) | Release summaries without prompt bodies |
agent_definition_version_get | Full version hash | Frozen README template, prompt, configuration and source revisions |
agent_definition_publish | expectedUpdatedAt; optional label | Captures and activates the saved draft |
agent_definition_activate | Full version hash, expectedUpdatedAt | Changes 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
- Call
assistant_getwith{}to check your existing pilot eligibility and discoverdreamlake-assistant. This read does not provision a session; execution availability is checked when you invoke. - Call
assistant_invokewith{ "assistantId": "dreamlake-assistant", "message": "Find my project notes" }. It sends one real turn to/agent/chatand waits up to 180 seconds. - Call
assistant_session_getwith the returnedsessionId, or read the returneddreamlake://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:
For Claude Code, a stdio entry can expand the same local environment variables:
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.