OpenProject CE MCP Server

Overview Schema Source Related Servers Discussions Admin

Delete attachment

delete_attachment

Destructive

Permanently deletes one OpenProject attachment after explicit confirmation, useful for removing wrong or superseded files. No undo; verify the attachment ID first.

Instructions

Permanently delete one attached file from OpenProject.

Use it only on explicit user instruction, for example to remove a file uploaded to the wrong work package or a superseded document. The attachment's metadata is read first so the result names the file and the container it was attached to, and so an unknown id fails before anything is removed.

Returns the attachment id, the file name, its container and a confirmation message.

Pitfalls: this deletes the file itself, not a link to it — every work package, wiki page or comment that embedded it loses the image or download. Deleting needs edit permission on the container (or authorship for a file that has no container yet), so a 403 can follow a successful read. A 404 means the id is unknown or already deleted; a second call on the same id answers 404 rather than succeeding. Removing a file does not remove the comment or work package that referenced it.

Related: list_attachments shows the ids and file names of everything a container holds; upload_attachment adds a replacement; download_attachment saves a copy first if the bytes are still wanted.

Input Schema

Name	Required	Description	Default
`confirm`	No	Must be true. Ask the user to confirm first: OpenProject offers no undo and no trash. Calling with confirm=false returns a confirmation_required error and nothing is read or deleted.
`attachment_id`	Yes	Numeric attachment id from list_attachments or get_work_package(include=['attachments']). Never a work package or container id — deleting the wrong id cannot be undone.

Output Schema

Name	Required	Description	Default
`id`	Yes
`deleted`	Yes
`message`	Yes
`container`	No
`file_name`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed11 schema fields changedv0.4.0Oct 24, 2026

removedOutput schema / description

Removed value: -"Outcome of ``delete_attachment``."

changedOutput schema / properties / container / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "description": "A reference to another resource. Canonical output shape.",
-    "properties": {
-      "id": {
-        "anyOf": [
-          {
-            "type": "integer"
-          },
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Resource id."
-      },
-      "name": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Human-readable name."
-      }
-    },
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "id": {
+        "type": [
+          "integer",
+          "string",
+          "null"
+        ]
+      },
+      "name": {
+        "type": [
+          "string",
+          "null"
+        ]
+      }
+    },
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / container / default
```
Removed value: -null
```

removedOutput schema / properties / container / description

Removed value: -"Object the file was attached to (work package, wiki page, meeting, ...); null for an uploaded file that was never claimed by one."

removedOutput schema / properties / deleted / description

Removed value: -"True once OpenProject accepted the deletion."

removedOutput schema / properties / file_name / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

removedOutput schema / properties / file_name / default
```
Removed value: -null
```

removedOutput schema / properties / file_name / description

Removed value: -"Name of the file that was removed, read before deleting it."

addedOutput schema / properties / file_name / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / id / description

Removed value: -"Id of the attachment that was deleted."

removedOutput schema / properties / message / description
```
Removed value: -"Human-readable confirmation."
```

First observedv0.1.0Aug 12, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Goes well beyond the annotations (destructiveHint/idempotentHint) by explaining that metadata is read before deletion so unknown ids fail first, that deletion needs edit permission (403 can follow a successful read), and that a repeat call returns 404 rather than succeeding. It also discloses the true blast radius — embedded references lose the file, and removing a file does not remove referencing comments or work packages.

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

Conciseness4/5

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

Front-loaded with purpose and usage, then organized into return values, pitfalls, and related tools — every section is scannable. It is on the long side, but the sentences carry distinct, non-redundant information rather than padding.

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 destructive tool with an output schema, the description covers what an agent needs: preconditions, error semantics, irreversibility, permission requirements, and the correct sibling tools. No critical decision-relevant gap remains.

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

Parameters4/5

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

Schema coverage is 100% and both params are described there, so the baseline is 3. The description earns extra credit by clarifying the confirm-gate behavior pattern (confirmation_required, nothing read or deleted) and warning that attachment_id is never a container or work package id, matching the irreversible consequence.

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?

States a specific verb ('Permanently delete') and resource ('one attached file from OpenProject'), with the scope narrowed to a single file. It is clearly distinguishable from siblings like delete_work_package or delete_project, and the 'Related' section reinforces the boundary against list/download/upload_attachment.

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?

Explicitly tells the agent when to use it ('only on explicit user instruction') and gives concrete examples (wrong work package upload, superseded document). It names alternatives and their conditions: list_attachments to discover ids, upload_attachment for a replacement, download_attachment to preserve bytes first.

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

Deploy Server