AI Clients | Dokki Docs

Use an external MCP client when you want an AI tool outside Dokki to search, read, create, or update Dokki resources. Dokki supports Streamable HTTP MCP clients including Claude, Claude Desktop, Claude Code, Codex CLI, Codex App, Cursor, and compatible custom clients.

Recommended endpoint

Use the canonical facade endpoint for every new connection:

https://dokki.one/mcp/v2

It exposes eight high-level tools — find, read, create, edit, share, message, publish, and connect — plus preview_resource. Each facade accepts an action, top-level resource or workspace ids, and an args object. This compact surface is easier for agents to discover and includes publishing and connected-app access when the credential permits them.

The legacy flat endpoint https://dokki.one/api/mcp remains available for older client configurations. It exposes many individual tools instead of the facade surface. Use /mcp/v2 unless an existing integration explicitly depends on the legacy tool names.

Before you connect

Sign in to the Dokki account that owns or can access the required workspaces.
Decide whether the client needs Personal, an entire Organization, selected workspaces, or exactly one workspace.
Start with read access and a non-sensitive test resource.
Never paste an API key or connector token into a Dokki document, chat, screenshot, or source repository.

Open Workspace → Extensions → Connect → AI Clients, then choose Set up a client. The dialog shows current instructions for Claude, Codex, Claude Code, and Cursor and lets you choose OAuth or API Key.

Choose an authorization method

OAuth — recommended for a person using an interactive client

Choose OAuth when the client can open a browser for sign-in.

Add https://dokki.one/mcp/v2 to the client.
Start the connection. The client discovers Dokki's OAuth configuration and opens Dokki in a browser.
Sign in to Dokki.
On the consent screen, choose any combination of Personal, one or more Organizations, and specific Workspaces.
Review the selected scope and approve.
Return to the client and run a read-only test.

Selecting Personal covers eligible Personal workspaces. Selecting an Organization covers that Organization namespace, including eligible workspaces added later, while specific Workspace selections stay limited to those workspaces. Organization membership, workspace membership, resource sharing, private-resource rules, and archived-workspace exclusion still apply. OAuth never turns a viewer into an editor or reveals a private resource.

To add or remove scope later, reconnect or reauthorize and make a new consent selection. Do not assume that passing a different workspace_id can expand an existing grant.

API Key — for a trusted non-interactive client

A Dokki API key starts with dk_. Generate it from the client setup dialog or Account settings.

A key is scoped to the current Personal context or one Organization.
It is not limited to one workspace; use a Workspace Connector when that boundary is required.
The raw key is shown when created. Store it in the client's credential store or secret manager.
Send it as Authorization: Bearer YOUR_API_KEY.
Revoke the key when the client, owner, or machine changes.

An API key still uses the acting user's Dokki permissions. A valid key does not bypass Organization membership, workspace roles, private resources, archived workspaces, or action-specific permission checks.

Workspace Connector — for one fixed workspace

A Workspace Connector is created by a workspace admin and is locked to exactly one workspace. Use it for a CI job, shared automation, dedicated agent, or machine that must not reach other workspaces.

The connector provides a self-contained URL containing the workspace id, connector id, and one-time token. Copy it when it is created and store it securely. See Workspace Connectors for Documents, Publish, and Memory connector flavors, client snippets, rotation, and revocation.

Claude and Claude Desktop

For Claude or Claude Desktop with custom connectors:

Open Settings → Connectors → Add custom connector.
Enter https://dokki.one/mcp/v2.
Complete Dokki OAuth in the browser.
Return to Claude and confirm that Dokki tools appear.
Ask for a read-only operation, such as listing accessible workspaces.

If the client requests a manual bearer credential instead of OAuth, use a dk_ API key or a Workspace Connector URL appropriate to the required scope.

Claude Code

For a direct OAuth connection, run:

claude mcp add dokki --transport http https://dokki.one/mcp/v2

Then start Claude Code, complete browser authorization, and confirm the Dokki server is connected. The Dokki Claude Code plugin may also bundle this same endpoint with Dokki skills and commands; use the plugin when you want both the MCP server and task guidance.

For API-key authentication, add the same endpoint with the header shown in Dokki's setup dialog. Keep the key outside shell history and project files.

Codex CLI and Codex App

The Dokki plugin is the preferred Codex App path: install Dokki, complete OAuth, and select the workspaces or Organizations it may access. The plugin uses the /mcp/v2 facade and provides Dokki-specific skills.

For a manual Codex CLI connection, add this to ~/.codex/config.toml:

[mcp_servers.dokki] command = "npx" args = ["-y", "mcp-remote", "https://dokki.one/mcp/v2"]

Restart Codex, complete OAuth, and verify that the server exposes find, read, create, edit, share, message, publish, connect, and preview_resource.

For API-key authentication, use the generated configuration in Dokki's setup dialog so the Authorization header is passed by the bridge. Do not commit the key in a repository-level config.

Cursor

Add this to ~/.cursor/mcp.json:

{"mcpServers":{"dokki":{"url":"https://dokki.one/mcp/v2"}}}

Restart Cursor and complete OAuth. If Cursor requires a manual credential, use the API-key version generated by Dokki, with Authorization: Bearer YOUR_API_KEY in the server headers.

Other MCP clients

For any Streamable HTTP-compatible client:

Server URL: https://dokki.one/mcp/v2
Preferred authentication: OAuth discovery
Alternative authentication: Authorization: Bearer dk_...
Fixed-workspace authentication: use the complete Workspace Connector URL
Transport: stateless Streamable HTTP

The client must preserve the exact connector URL and query parameters when using a Workspace Connector.

AI Client capabilities

New AI Client connections should use https://dokki.one/mcp/v2. It uses Streamable HTTP and exposes eight discoverable facade tools plus preview_resource. The credential scope and current Dokki permissions decide which actions actually succeed.

find

List authorized workspaces, browse resources, search by meaning, grep exact text or identifiers, discover related knowledge, and list Artifact templates.

read

Read documents, tables, artifacts, and files. Documents support view, outline, and edit-addressing modes; tables support filters, sorting, projection, pagination, and aggregation.

create

Create folders, documents, tables, artifacts, and files. Tenant-scoped credentials may also create workspaces when the selected Personal or Organization scope permits it.

edit

Rename, move, tag, untag, or archive resources; edit document nodes; change table rows, columns, and cells; and update Artifact source. Destructive operations and supported concurrent writes add confirmation or compare-and-set boundaries.

Share a resource with a user or change public access when the acting identity may manage sharing. Public-sharing changes require confirmation.

message

List workspace Channel members and send or read Channel messages. Available review actions remain subject to workspace membership and the current message facade.

publish

Manage an authorized workspace's public site, published resources, featured content, and custom domain. Publishing a resource requires confirmation.

connect

List, authorize, inspect, disconnect, and call supported external integrations through the acting user's connected accounts. This is the MCP representation of the product's MCP Apps direction.

preview_resource

Open a rendered inline preview for a document, table, or Artifact in MCP hosts that support MCP Apps UI resources. Use normal read actions when structured data is sufficient.

How AI Client authorization is evaluated

Authenticate the OAuth grant, dk_ API Key, or Workspace MCP Connector.
Resolve Personal, Organization, selected-workspace, or fixed-workspace scope.
Confirm the acting identity still belongs to the tenant and can access the workspace.
Apply private-resource and resource-role checks.
Apply the facade action's read, write, share, publish, message, or external-app requirement.
Require confirmation for protected consequential actions.

A client may discover a tool while a specific call is still denied. Tool discovery is not proof that every workspace, resource, or action is authorized.

Endpoint compatibility

Recommended: https://dokki.one/mcp/v2 — the facade-based AI Client surface.
Compatible legacy endpoint: https://dokki.one/api/mcp — many individual tools; keep it only for existing configurations that have not migrated.
Legacy Organization URLs such as /api/mcp/org/<orgId> remain compatibility paths. New OAuth connections select Personal, Organization, and Workspace scope during consent.
Workspace MCP Connectors reuse the appropriate endpoint with a fixed workspace, connector id, and connector token in the generated URL. Always copy the complete generated URL.

Verify the connection end to end

Run these checks in order:

Tool discovery — confirm the expected facade tools are visible.
Identity and scope — call find with action: "workspaces" and check that only intended workspaces appear.
Read — list resources in one allowed workspace, then read a known document.
Write boundary — only if required, create or edit a disposable test resource and read it back.
Denied boundary — confirm an unselected workspace or unauthorized resource is not exposed.
Cleanup — remove the test resource and verify it is absent.

A successful connection does not prove every operation is allowed. Each action is checked again against credential scope, current membership, resource permissions, and action-specific requirements.

Troubleshooting

No browser opens — start authorization again from the client's MCP settings; confirm the client supports remote OAuth.
401 Unauthorized — the token or key is missing, expired, revoked, malformed, or attached to the wrong endpoint. Reauthorize or replace the credential.
403 Forbidden — authentication succeeded, but the selected scope or current Dokki role does not permit the operation.
Workspace missing — reauthorize OAuth and select Personal, the Organization, or the specific workspace; also confirm it is not archived and that your account can access it.
Wrong workspace appears — revoke the connection and create a grant with the intended selection.
Tools are missing — confirm the client uses /mcp/v2, refresh tool discovery, and restart the client. A Workspace Documents Connector intentionally omits publish and connect.
Old flat tool names appear — the client is using /api/mcp; migrate it to /mcp/v2 when compatible.
Write denied after reads succeed — the credential can reach the resource, but the acting identity lacks edit or manage permission.
Connector scope mismatch — use the full generated connector URL. A different workspace id or connector id is rejected.
Connection works but an external app does not — MCP client access to Dokki and Dokki's outbound MCP Apps are separate. Check Connect → MCP Apps and the acting user's app connection.

Review who currently has access

Open Connect → AI Clients and review Authorized clients before using recent activity as an access check. This account-level list includes grants for Personal, organizations, and individual workspaces, and labels each grant as active, expired, or revoked.

If the list cannot be loaded, Dokki shows an error instead of an empty state. Recent activity answers a different question: a quiet client can still hold an active grant, while an old activity entry can belong to an expired or revoked grant.

Revoke access

OAuth: remove or reconnect the AI Client from Dokki or the client.
API Key: revoke the dk_ key in Account settings.
Workspace Connector: revoke it in Workspace → Extensions → Connectors.
MCP App: disconnect the external account under Connect → MCP Apps.

Revocation stops future tool calls. It does not delete documents, imports, messages, or external-service changes already created.