Dokki Docs logo

Workspace MCP Connectors

Workspace Connectors are admin-managed MCP credentials locked to one Dokki workspace. Use them when a machine, automation, CI job, shared agent, or external client must work inside one workspace without inheriting access to the rest of a user's Personal or Organization context.

When to use a Workspace Connector

Choose a Workspace Connector when all of these are true:

  • The caller should stay inside one named workspace.

  • Browser OAuth is unavailable, undesirable, or tied to the wrong human lifecycle.

  • Several users must not share one person's dk_ API key.

  • You need a credential that can be revoked without interrupting unrelated clients.

Use OAuth instead for an interactive client that should follow a person's selected Personal, Organization, or multi-workspace access. Use an API key when a trusted non-interactive client needs one complete Personal or Organization tenant.

Who can manage connectors

Only workspace admins can create, list, or revoke connectors.

Open Workspace → Extensions → Connectors. Review the workspace name before creating anything; a connector cannot be moved to another workspace after creation.

Choose a connector flavor

Documents

Endpoint: https://dokki.one/mcp/v2 with the generated workspace, connector, and token query parameters.

The Documents connector exposes:

  • find — browse this workspace, search, grep, related knowledge, and Artifact templates.

  • read — documents, tables, artifacts, and files.

  • create — folders, documents, tables, artifacts, and files inside this workspace.

  • edit — resource organization and document, table, and Artifact updates.

  • share — sharing actions allowed by the connector's acting workspace identity.

  • message — workspace Channel coordination.

  • preview_resource — rendered previews for supported resources.

It intentionally does not expose the publish facade or the acting user's personal connect integrations. Global actions such as listing all workspaces or creating another workspace are rejected.

Publish

Endpoint: /api/publish-mcp in the generated connector URL.

The Publish connector is limited to the public site belonging to this workspace. It can get, create, or update the site; publish or unpublish resources; list published resources; and manage custom-domain status when the acting workspace authority permits it.

A Publish connector does not provide general document editing, other workspaces' sites, personal external apps, or Memory.

Memory

Endpoint: /api/mem-mcp in the generated connector URL.

The Memory connector can add, search, list, and delete durable facts in this workspace's long-term memory. It does not provide documents, publishing, personal external apps, or another workspace's memory.

Create a connector

  1. Open Workspace → Extensions → Connectors.

  2. Select New connector.

  3. Enter a name that identifies the client and purpose, such as “Patsnap retrieval test” or “Docs publish automation.”

  4. Choose Documents, Publish, or Memory.

  5. Create the connector.

  6. Copy the generated token, full URL, and the client configuration you need before closing the dialog.

  7. Store the result in the client's secure credential store or a secret manager.

  8. Add it to only the intended client.

  9. Run the verification flow below.

The raw token is shown only at creation time. Dokki keeps a hash and a visible prefix for later identification; it cannot display the original token again.

Understand the generated URL

The full connector URL contains:

  • The endpoint path for the selected flavor.

  • workspace_id — the one allowed workspace.

  • connector_id — the connector record.

  • api_key — the one-time connector token.

Treat the complete URL as a secret. Do not remove or alter its query parameters. Dokki checks that the token flavor, stored workspace, URL workspace id, and URL connector id all agree. A caller cannot widen scope by replacing a workspace id in the URL or tool arguments.

Add the connector to a client

The creation dialog provides paste-ready configurations for supported clients.

Claude Desktop or a JSON-based MCP client

Copy the generated JSON snippet. It adds a named server whose url is the complete connector URL.

Codex CLI

Copy the generated TOML snippet into ~/.codex/config.toml. It has the form:

[mcp_servers.dokki] url = "COMPLETE_GENERATED_CONNECTOR_URL"

Use the flavor-specific server name shown by Dokki when configuring separate Documents, Publish, and Memory connectors.

Codex App environment configuration

Copy the generated DOKKI_MCP_URL=... value into the environment or secret setting used by the intended Codex task. Do not put it in a repository file.

Agent MCP configuration

Open the installed Agent's MCP tab and add the generated connector URL only when that Agent should use this workspace-scoped service. The Agent's own workspace access and execution permissions continue to apply; adding a connector does not grant unrelated workspace access.

Other clients

Use the full URL exactly as generated. If the client separates URL and credentials, prefer the paste-ready configuration shown by Dokki instead of manually extracting the token.

Verify a Documents connector

  1. Refresh tool discovery.

  2. Confirm find, read, create, edit, share, message, and preview_resource are visible.

  3. Confirm publish and connect are absent.

  4. Browse resources without supplying another workspace id.

  5. Read a known non-sensitive resource.

  6. If writes are required, create a disposable document, read it back, then remove it.

  7. Attempting to address another workspace must fail or return no resource.

  8. Read back cleanup and confirm the disposable resource is absent.

Verify a Publish connector

  1. Confirm only publishing and domain tools appear.

  2. Read the current site for this workspace.

  3. List its published resources.

  4. Do not publish a test resource unless public exposure is intended and authorized.

  5. Confirm another workspace's site cannot be addressed.

Verify a Memory connector

  1. Confirm only memory tools appear.

  2. Search for a known non-sensitive fact.

  3. If write testing is authorized, add a run-owned fact, read it back, delete it, and verify absence.

  4. Confirm another workspace's memory cannot be addressed.

Permission boundaries

A Workspace Connector fixes the workspace boundary, but it does not turn every operation into an unconditional success.

  • The connector is associated with the admin who created it.

  • Resource, sharing, Channel, Publish, and other action checks still apply.

  • Private, archived, deleted, or otherwise unavailable resources remain unavailable.

  • Dangerous or externally visible actions may require confirmation.

  • Documents, Publish, and Memory flavors cannot be exchanged.

  • A revoked connector stops authorizing new requests.

Use separate connectors

Create separate connectors for:

  • Different clients or machines.

  • Production and testing.

  • Read-oriented retrieval and workflows that can mutate content.

  • Documents, Publish, and Memory.

  • Different vendors or external teams.

  • Automations with different owners or retirement dates.

Separation limits the impact of one exposure and lets you revoke a single integration without interrupting the others.

Status and auditing

The connector list distinguishes active, expired, and revoked credentials and can show creation and last-used dates when available. A revoked connector remains as a lightweight audit record instead of disappearing.

Use clear names so activity can be attributed to the correct client. Recent use is useful evidence, but current connector status remains the authorization source of truth.

Rotate or revoke

Dokki does not reveal an existing raw token. To rotate:

  1. Create a replacement connector with the same flavor and a new name.

  2. Update the intended client with the new generated URL.

  3. Run a read-only verification.

  4. Revoke the old connector.

  5. Confirm the old client can no longer call Dokki.

Revoke immediately if a connector URL appears in a document, prompt, screenshot, log, source repository, or unintended client.

Troubleshooting

  • 401 Invalid or expired connector token — use the exact newly generated URL or replace a revoked credential.

  • Wrong flavor — a Documents token cannot authenticate to Publish or Memory, and vice versa.

  • URL workspace mismatch — restore the original generated workspace_id; never edit scope manually.

  • URL connector mismatch — use the URL copied from the same connector record as the token.

  • Missing publish or connect tools — this is expected for Documents Workspace Connectors.

  • Global action rejected — fixed-workspace credentials cannot list every workspace or create an unrelated workspace.

  • Resource not found — confirm the resource belongs to this workspace and is still available to the connector's acting identity.

  • Write or share denied — the fixed workspace is correct, but the action-specific permission is not.

  • Client still uses an old connector — restart the client and remove cached or duplicate server entries.

Revoking a connector prevents future calls. It does not undo resources, publications, messages, or memory changes already completed.

Workspace MCP Connectors | Dokki Docs