<!-- source: https://docs.dreamlake.ai/lakeshore/agents/mcp @ 0.1.192 b2f973b1 -->
# 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:

| 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](/workspaces/project-access.md#interface-coverage).

## Source visibility

The source-only adapter in a checkout containing [PR #1944](https://github.com/dreamlake-ai/dreamlake-workspace/pull/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](/sources.md#visibility-and-sharing).

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:

```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](/infrastructure-stacks.md#move-a-registration),
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](/notes/agent-presence/#source-bound-human-selections).
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.

| 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:

```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.

| 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](/agents/authoring.md#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](https://learn.chatgpt.com/docs/extend/mcp?surface=cli) and
[Claude Code MCP configuration](https://code.claude.com/docs/en/mcp).

Protocol references: [official TypeScript SDK](https://ts.sdk.modelcontextprotocol.io/v2/),
[stdio serving](https://ts.sdk.modelcontextprotocol.io/v2/serving/stdio.html), and
[MCP authorization](https://modelcontextprotocol.io/specification/2026-07-28/basic/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](/annotations/reference.md).
