Dokman

Connect an AI Assistant ​

Purpose ​

MCP lets an AI client - Cursor, Claude, ChatGPT, VS Code, or anything else that speaks the Model Context Protocol - read your Dokman data and act on it. The client talks to the Dokman API, the API talks to your Dokploy, and every call is checked against the access your account already has. Nothing is exposed that you couldn't see yourself.

This page covers connecting a client, what the consent screen means, and what the assistant can reach afterwards. The full tool list is in MCP Tools Reference.

Before you start ​

  • An AI client that supports remote MCP servers over HTTP (most current ones do).
  • A Dokman account with a connected workspace - the same sign-in you use in the app.

Permissions ​

  • Any account with access to the workspace - the client sees and does exactly what you can do in Dokman.
  • No separate Dokman tier - MCP follows your Dokploy permissions, not a plan. Admin-only screens in Dokman stay admin-only here.

User Flow ​

Add the Dokman server to your AI client ​

Step 1: Copy the address

  1. Copy the Dokman API address with /mcp on the end: https://dev-api.dokman.dev/mcp.
  2. The read-only variant of the same address - /mcp/readonly - works too, if you want an assistant that can never deploy anything.

Result:

  • You have the one address your AI client needs.

Step 2: Add it as a remote server

  1. In your AI client, open the MCP or connectors section and add a remote server (not a local one).
  2. Paste the address. Most clients register the client for you automatically - nothing to copy back here.
  3. Your client opens your browser at the consent page. If it doesn't, open the connection from the client again.

Result:

  • Your browser shows a MCP CONNECT page asking to connect the client to Dokman.

Review the consent page ​

Step 3: Read what you're approving

  1. The page is titled Connect {client} to Dokman? - the client name comes from the app that asked.
  2. Grants access to names the workspace the grant will cover. Results go to names the host the answers are sent back to.
  3. Under This client would be able to you see two rows: Read and Deploy.

Result:

  • You know which client is asking, which workspace it gets, and where the answers go.

Note:

  • The grant covers the workspace that was selected in Dokman when this page opened. If you have more than one workspace, switch to the right one in the app first, then start the connection again.

Choose what the assistant may do ​

Step 4: Set the Deploy toggle

  1. Read is always granted: projects, services, deployments, and logs.
  2. Deploy has a toggle, on by default. On means the assistant can trigger deployments and related actions. Off means read-only - the deploy actions stay in the client's list, but any attempt to run one is refused.
  3. Some clients ask for read-only by default. The page notes that deploy is included by your choice - leave the toggle on if you want the assistant to ship code.

Result:

  • The grant is exactly as wide or as narrow as you set it.

Step 5: Approve or cancel

  1. Tap Authorize. Your browser returns to the client, and the connection completes on its own.
  2. Tap Cancel instead to refuse. The client is told the request was declined and nothing is granted.

Result:

  • The client is connected - or cleanly refused.

Let the assistant work ​

Step 6: Ask it something

  1. The client now holds a pass that lasts an hour and refreshes itself silently for up to 30 days. You won't be asked to sign in again for each request.
  2. Read-only work ("which services are failing?", "show me the last deploy log") works immediately.
  3. Deploy work ("deploy the api service", "restart that container") works too when the Deploy toggle was on. The assistant is told to confirm with you before it changes anything.

Result:

  • The assistant works on your Dokman data under your permissions.

End the connection ​

Step 7: Cut a client off

  1. Remove the server in your AI client and delete the credentials it stored there. That is where the connection lives - Dokman doesn't keep a list of AI clients in the app.
  2. If you just want a narrower grant, connect again from the client and set the Deploy toggle the other way.
  3. The browser only reopens when the grant runs out, when you move to another workspace, or when the client asks for more than it had before.

Result:

  • The client stops working, or comes back with a smaller job.

What the assistant can and cannot do ​

It can:

  • List your projects and services, read deployment and service logs, check server health, and read your notification history
  • With Deploy on: deploy, rebuild, restart, redeploy a Compose stack, and cancel a running deployment - only for services you already have access to

It cannot:

  • Reach a workspace you haven't connected, a project you aren't a member of, or another team entirely
  • Reach Dokman screens that have no tool behind them - Servers, Metrics Token, Backups, Alert Thresholds, and the Terminal
  • Use your Dokman session anywhere else - the grant only works against the MCP endpoint
  • See your password, API keys, environment variables, or secrets - those are never sent to the client

Note:

  • Every tool call is recorded - who called, which tool, which service, and whether it was allowed. Bodies and secrets are not stored.

Screens Involved ​

  • The consent page in your browser (MCP CONNECT, Authorize, Cancel)
  • Dokman app or web app, if you need to sign in or switch workspace first
  • The AI client itself, where the connection and its tools live

Inputs ​

User Inputs:

  • The MCP address pasted into the AI client
  • The Deploy toggle on the consent page
  • Authorize or Cancel

Outputs ​

  • A scoped grant for one workspace, held by the client
  • An audit trail of the tool calls it makes
  • Deployment and log answers returned into the client

Error Handling and Edge Cases ​

ScenarioSystem Behavior
The client reports the connection failedThe pass expired or was refused - remove the server and add it again
The assistant can read but not deployThe grant was read-only - reconnect with the Deploy toggle on
Deploy actions are missing from the client's tool listThe client is pointed at the read-only address - reconnect using the full address
"Invalid authorization request" on the pageThe handoff lost its parameters - close the tab and start again from the client
"State already used."The page was opened twice, or an old tab was reused - start again from the client
"Workspace not found. Reconnect the workspace first."The workspace changed after the page opened - reconnect it in Dokman, then start again
"Too many authorization requests"Too many connection attempts in a short window - wait about 15 minutes
The client asks to reconnect every timeThe client keeps asking for read-only - approve with Deploy on, or it can never deploy
The assistant can't find a projectThat project isn't shared with your account - ask a Dokploy admin

Released under the Dokman license. English only.

Copyright © Dokman