docker-mcp-server

Overview Schema Source Related Servers Discussions Admin

swarm_update

Update Docker swarm settings and rotate join tokens or unlock key on a manager node. Merges changes into the current cluster spec for token rotation and configuration updates.

Instructions

Update swarm-wide settings: the single home for join-token rotation and cluster spec changes.

Must be called on a swarm manager node. Token rotation invalidates the old join token immediately - nodes that have not yet joined using the old token must use the new one. Existing joined nodes are unaffected. Use swarm_join_tokens to retrieve the new tokens after rotation. Rotating the unlock key requires all managers to be re-unlocked on restart with the new key; retrieve it immediately via swarm_unlock_key. Rotation and updates are independent and may be combined in one call; swarm_init sets these same fields when the swarm is first created, and swarm_inspect reads the current values back.

The Engine replaces the whole cluster spec on every update, so this reads the current spec first and resubmits it, merging updates over it - omitting updates therefore changes nothing but the requested rotation.

Args: rotate_worker_token: Issue a new worker join token, invalidating the current one rotate_manager_token: Issue a new manager join token, invalidating the current one rotate_manager_unlock_key: Issue a new autolock unlock key for manager restart updates: Engine SwarmSpec fields to change, merged over the current spec one top-level key at a time, so a named block is replaced whole rather than field by field: keys are "Name", "Labels", "Orchestration", "Raft", "Dispatcher", "CAConfig", "EncryptionConfig" and "TaskDefaults", e.g. {"EncryptionConfig": {"AutoLockManagers": True}} to turn manager autolock on. Read the current blocks from swarm_inspect

Returns: bool: True after the update completes

Input Schema

TableJSON Schema

Name	Required	Description	Default
`updates`	No
`rotate_worker_token`	No
`rotate_manager_token`	No
`rotate_manager_unlock_key`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv2.2.6Sep 10, 2026
- addedInput schema / properties / updates
```
Added value: +{
+  "default": null,
+  "type": "object"
+}
```
Addedv2.0.0Jul 4, 2026

TDQS

A5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses key behavioral consequences beyond the annotations: old join tokens invalidate immediately, existing joined nodes are unaffected, unlock-key rotation forces re-unlock on restart, and the Engine replaces the whole cluster spec by reading the current spec and merging updates. This goes well beyond the sparse annotations, and no contradiction exists.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but information-dense: every sentence covers a distinct fact such as purpose, prerequisite, consequences, merge behavior, parameter meanings, and return type. It is front-loaded with the purpose and organized with Args/Returns sections, making it easy to scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex, zero-required-parameter mutation tool with no schema descriptions, the description covers prerequisites, side effects, merge semantics, all parameter meanings, related retrieval tools, and return type. Nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, but the Args section fully documents every parameter: each rotation flag is described with its invalidation effect, and updates explains merge semantics, enumerates allowed top-level keys, and gives a concrete example. This fully compensates for the bare input schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Update swarm-wide settings: the single home for join-token rotation and cluster spec changes,' naming a specific verb, resource, and scope. It also positions the tool relative to swarm_init, swarm_inspect, swarm_join_tokens, and swarm_unlock_key, so an agent can distinguish it from sibling swarm tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states the prerequisite 'Must be called on a swarm manager node' and gives explicit routing: use swarm_join_tokens to fetch new tokens, swarm_unlock_key for the unlock key, swarm_init for initial creation, and swarm_inspect to read current values. It also explains when rotation and updates can be combined and that omitting updates changes nothing but rotation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server