Add safe application env upsert MCP tool

[agentHits]

Summary

Dokploy MCP needs a safe tool for partial application environment variable updates once the core API from Dokploy/dokploy#4581 lands.

Related core work:

• Dokploy core feature request: Add safe partial environment variable upsert API and MCP tool dokploy#4525
• Dokploy core implementation PR: feat: add safe application env upsert dokploy#4581

Suggested MCP tool capability:

application.env.upsert({
  applicationId,
  variables,
  redeploy?,
  dryRun?,
  expectedRevision?,
})

Why this is needed

Today, MCP clients can only rely on full environment replacement-style operations for application env changes. That is unsafe for AI agents and automation when the current env is redacted or intentionally hidden.

If an agent wants to add one variable, such as REDIS_URL, it must not reconstruct the full env block from partial/redacted data. Doing that can accidentally delete existing secrets like database credentials, API keys, OAuth secrets, webhook secrets, or provider credentials.

A server-side partial upsert endpoint lets the Dokploy server read and merge the current env internally while MCP sends only the requested variables.

Required MCP behavior

The MCP tool should:

• send only submitted variables to Dokploy;
• never request, reconstruct, or overwrite the full current env block client-side;
• never call application.saveEnvironment as a fallback implementation path;
• never return raw secret values;
• support dryRun so agents can preview changes;
• support redeploy if the caller wants to redeploy after env update;
• support expectedRevision if the core API exposes it for stale-write protection;
• return metadata only, for example:

{
  applicationId: string
  changed: boolean
  revision: string
  dryRun: boolean
  redeployed: boolean
  variables: Array<{
    name: string
    action: "created" | "updated" | "unchanged"
    secret: boolean
  }>
}

Automation use cases

This unlocks safer MCP-driven workflows such as:

• create Redis/Postgres/S3/ClickHouse resources and attach selected connection variables to an app;
• run dryRun first, show the user what would change, then apply;
• update one integration secret without exposing or rewriting unrelated secrets;
• optionally redeploy the application after a safe server-side env merge.

Implementation direction

Dokploy/mcp appears to generate tools from the Dokploy OpenAPI spec. The MCP implementation should prefer that pipeline instead of a hand-written tool:

• update src/generated/openapi.json from the stable core OpenAPI source;
• regenerate src/generated/tools.ts;
• regenerate TOOLS.md;
• add focused MCP tests for tool exposure/schema/routing.

If the endpoint is not yet available in the published Dokploy OpenAPI because Dokploy/dokploy#4581 has not merged yet, the MCP PR should be clearly marked as dependent on the core PR and should not be merged until maintainers confirm the API/OpenAPI source is stable.

Security acceptance criteria

• No raw existing env values are read by MCP.
• No raw secret values are returned in MCP output.
• No real secrets appear in tests, generated docs, issue comments, or PR comments.
• No client-side read-modify-write over the full env block.
• No fallback to full saveEnvironment.
• Tests cover dryRun.
• Tests cover call routing to the partial upsert endpoint.
• Tests or mocked MCP responses prove raw submitted values are not returned.

Maintainer coordination

The original core issue and implementation PR were opened by @agentHits.

Review/help from Dokploy maintainers or code owners would help align the MCP surface with the final core API shape. @Siumauricio, if this API/MCP surface is in your review scope, a quick confirmation after Dokploy/dokploy#4581 is reviewed would help move the MCP side safely toward production.