MCP Tools Reference

Purpose

The exact tools an AI client can call over MCP, what each one takes, and what comes back. Tools are the only way an assistant touches your Dokman data - there is no blanket API access behind them.

For the setup flow, see Connect an AI Assistant.

---

How a tool call works

1. The client sends the tool name and its arguments.
2. Dokman checks the grant: which workspace, which scopes, and whether your account can reach the target.
3. On success you get a JSON payload. On a refusal you get a JSON payload with a code and a message - the call itself succeeds, the action doesn't.
4. Every call, allowed or refused, is written to the audit log.

---

Read tools

Available to every grant, including read-only ones.

Tool	What it does	Parameters
dokman_list_projects	Lists the projects your account can see	limit (1-100, default 50), offset
dokman_list_services	Lists apps, Compose stacks, and databases	projectId, kind (app / compose / database / all), query (max 120 chars), limit, offset
dokman_get_service	Looks up one service by id	serviceId, kind (accepted, unused)
dokman_list_deployments	Lists deployments, newest first	serviceId, status (success / failed / running / cancelled), limit, offset
dokman_get_deployment_logs	Fetches the log of one deployment	deploymentId, tail (1-2000, default 500)
dokman_get_service_logs	Fetches recent logs of one service	serviceId, tail
dokman_server_health	Checks that the linked Dokploy server is reachable	none
dokman_list_notifications	Lists this workspace's notification history	limit, offset, since

---

Deploy tools

Need the deploy scope. Without it the call is refused with insufficient_scope; on the read-only endpoint (/mcp/readonly) they are not offered at all.

Tool	What it does	Parameters
dokman_deploy_service	Starts a deployment for a service	serviceId
dokman_rebuild_service	Rebuilds a service without cache	serviceId
dokman_restart_service	Restarts a service (no deployment is created)	serviceId
dokman_cancel_deployment	Cancels a running deployment	deploymentId
dokman_redeploy_compose	Redeploys a Compose stack	composeId

Note:

• These are destructive. The client is told to confirm with you first, but the check that matters is your grant - a client with the deploy scope can act on any service you can act on.
• Deploy and rebuild can only target services you already have access to. A service in another project comes back as NO_ACCESS.

---

Result shapes

Shape	Comes from
{ items, truncated, nextOffset }	The three list tools - pass nextOffset back as offset to continue
{ id, name, kind, status, projectId, projectName }	dokman_get_service
{ deploymentId, lines, truncated }	The two log tools - logs are ANSI-stripped and cut at tail
{ serverId, url, reachable, projectCount, serviceCount, checkedAt }	dokman_server_health
{ serviceId, kind, deploymentId, status }	Deploy, rebuild, and Compose redeploy
{ deploymentId, status: "cancelled" }	dokman_cancel_deployment
{ serviceId, status: "restarted" }	dokman_restart_service

Note:

• A deploy can come back as pending: true with a note instead of a deployment ID. Dokploy reports nothing for the trigger itself, so the ID is read back from deployment history a moment later - the client is told to poll dokman_list_deployments.

---

Error codes

Code	What it means	Try this
NO_ACCESS	The service isn't in your account's scope	Check the project in Dokploy - if you can't see it there, the assistant can't either
NOT_FOUND	The service or deployment doesn't exist here	Re-read the list; the ID may be from another workspace
REQUIRES_REAUTH	Your Dokploy login expired or was rejected	Sign in again in Dokman, then retry
DOKPLOY_UNREACHABLE	Your Dokploy server didn't answer	Check the server is up and reachable, then retry
insufficient_scope	The grant is read-only and the tool needs deploy	Reconnect with the Deploy toggle on
401 / invalid_token	The pass expired, was revoked, or the client lost it	Remove and re-add the server in the client
400 (missing session)	The client skipped the handshake	The client re-initializes and continues
404 (unknown session)	The session ended	The client re-initializes and continues
405	Something tried to open a stream - only POST is served	Use a client that speaks streamable HTTP
429	Too many requests	Wait and retry - the limit is per token, not per IP

---

Limits

• One workspace per grant - a client connected to one workspace can't reach another.
• Access pass: 1 hour. It refreshes silently, for up to 30 days, without asking you again.
• Page size: 100 items at most, 50 by default. Log tail: 2000 lines at most, 500 by default.
• Sessions last 60 minutes on the client side; a dead session is re-created automatically.
• Rate limits are counted per token, so one chatty assistant never blocks the others.

---

Error Handling and Edge Cases

Scenario	System Behavior
A read tool returns NO_ACCESS	The target is outside your Dokploy access - the grant can't widen it
A list comes back with truncated: true	More items exist - page with nextOffset
Logs come back with truncated: true	The log was longer than tail - raise tail up to 2000
A deploy returns pending: true	The deployment is registered but not listed yet - poll dokman_list_deployments
dokman_server_health returns DOKPLOY_UNREACHABLE	Your Dokploy is down or unreachable - nothing will deploy until it is back
The client sees no deploy tools at all	It is pointed at the read-only endpoint (/mcp/readonly)
Two deploys land close together	Both may resolve to the same newest row - list the deployments to tell them apart