Completions

Clients that support MCP completions (VS Code, Claude) can suggest values while you fill a prompt argument or a variable of a resource template: type we in containerId and the client offers web and db-web. The client sends completion/complete with what you typed and the values you already chose; arcane-mcp answers with matching values from Arcane.

The server advertises the completions capability only when something can be completed (see Exclusions).

What completes

Argument or variable	Where	Values from	What is inserted
environmentId	every prompt; every arcane://environment/{environmentId}/... template	environment.list	The environment ID (0 is Arcane’s local host); the name is matched too
containerId	diagnose_container; arcane://environment/{environmentId}/container/{containerId}	container.list	The container name; its ID when you type the start of the ID
projectId	update_project_images; arcane://environment/{environmentId}/project/{projectId}	project.list	The project ID (Arcane finds a project by ID only); the name is matched
services	update_project_images	project.runtime of the chosen projectId	The project’s service names, completing the last item of the comma-separated list
imageId	security_report	image.list	The image ID (sha256:...); tags such as nginx:1.27 and the ID without sha256: are matched
volumeName	backup_volume	volume.list	The volume name; anonymous volumes (Docker’s com.docker.volume.anonymous label) come after the named ones
serviceId	rollback_service	swarm_service.list	The Swarm service name; its ID when you type the start of the ID
severity	security_report	the fixed set CRITICAL, HIGH, MEDIUM, LOW, UNKNOWN (no call to Arcane)	The severity in upper case, completing the last item of the list

Free text (symptom) is not completed.

Matching

• Matching ignores case. Values that start with what you typed come first, then values whose ID, name or tag starts with it, then values that merely contain it; within each group, in the order Arcane lists them.
• At most 100 values are returned (the MCP limit), with total (how many matched) and hasMore when some were left out: keep typing to narrow the list.
• Only values a prompt accepts are offered (letters, digits and ._-:/@), so a suggestion is never refused by prompts/get.
• In a list (services, severity), the items you already typed are kept and not offered again: web, w completes to web,worker.

The chosen environment and project

When the client sends the values you already chose (the request’s context arguments), they are used: a container, project, image, volume or Swarm service is looked up in the chosen environmentId, and services in the chosen projectId. Without an environmentId, the configured default environment (ARCANE_ENVIRONMENT_ID) is used, as the actions do; without a projectId, services offers nothing.

Same path, same credential

Completions run the catalog’s read actions the way resources do, with the server’s Arcane client: in HTTP mode each Arcane key has its own server, so you are offered what your key can see. There is no second HTTP path to Arcane. They are reads, so read-only and safe mode keep them, and they behave the same on the three tool surfaces.

Exclusions

An argument whose action is excluded (ARCANE_MCP_EXCLUDE_TOOLS) is not completed and the action is never called: exclude container.list and containerId offers nothing, while environmentId still completes. A prompt or template the server does not offer is not completed either. When nothing at all is left to complete, the server does not advertise the capability and completion/complete answers method not found (-32601).

Cache

Each list is kept for 5 seconds per server (so per Arcane key in HTTP mode): typing a value sends one request to Arcane, not one per keystroke, and requests that arrive together for the same list share one call. A call for a completion is bounded by 10 seconds (or by ARCANE_MCP_ACTION_TIMEOUT when shorter); if you close the suggestion box first, the call still finishes and serves the next request.

Errors

A suggestion is a hint, so a failing Arcane never breaks the client’s form:

• Arcane unreachable, a refused credential (401, 403), an unknown environment (404), Swarm not enabled (409) or a timeout: an empty list, not an error. The failure is kept for the same 5 seconds, so a failing Arcane is not asked on every keystroke.
• A prompt name the server does not offer: JSON-RPC error -32602 (invalid params), as prompts/get answers it.
• An argument nothing completes, or a URI that is not one of the offered templates: an empty list.

Each call to Arcane leaves one audit log record, msg=completion with surface=completion, tool=completion/complete, the action and its outcome (ok or error); what you typed is never logged. Answers from the cache leave none.