OpenProject CE MCP Server

Overview Schema Source Related Servers Discussions Admin

Set project favorite

set_project_favorite

Idempotent

Adds or removes a project from the authenticated user's OpenProject favorites (17+), letting them pin or unpin projects on their personal overview.

Instructions

Add or remove a project from the authenticated user's favorites (OpenProject 17+).

Favorites are per user, not per project: this changes what the account behind OPENPROJECT_API_KEY sees starred on its own overview page, and nothing about the project itself or about anybody else's view. Use it when the user asks to pin, star or favorite a project they work in.

Returns {id, favorite, message} — favorite is the state now in effect. The call is idempotent: favoriting an already-favorited project succeeds again.

Pitfalls: this endpoint only exists from OpenProject 17. When the instance reports a version older than that the call is REFUSED before anything is sent, with the detected version in the message, because there is no downgrade that would achieve the same thing — favorite the project in the web UI instead. When it reports no version at all the request IS sent, since an unreported version says nothing about the endpoint. A 404 is ambiguous on purpose in the hint: it means either the project does not exist for this account or the endpoint is missing. This is not project 'status' and not a work-package watcher.

Cross-references: list_projects(favorites_only=true) lists the current favorites (and works on older instances too); get_project resolves an identifier first; get_instance_info reports the detected OpenProject version.

Input Schema

Name	Required	Description	Default
`favorite`	Yes	true adds the project to the authenticated user's favorites, false removes it. Required — there is no toggle, so read the current state with list_projects(favorites_only=true) if you do not know it.
`id_or_identifier`	Yes	Numeric project id or URL identifier to favorite or un-favorite; both are accepted and come from list_projects or get_project.

Output Schema

Name	Required	Description	Default
`id`	Yes
`message`	Yes
`favorite`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed6 schema fields changedv0.4.0Oct 24, 2026

removedOutput schema / description

Removed value: -"Outcome of ``set_project_favorite`` (OpenProject >= 17)."

removedOutput schema / properties / favorite / description

Removed value: -"The state now in effect: true when the project was favorited, false when the favorite was removed."

removedOutput schema / properties / id / anyOf

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

removedOutput schema / properties / id / description

Removed value: -"Project id or identifier that was changed."

addedOutput schema / properties / id / type

Added value: +[
+  "integer",
+  "string"
+]

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

First observedv0.1.0Aug 12, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Adds real context beyond the annotations: the change is per-account and invisible to others, an already-favorited project succeeds again, and the call is REFUSED before sending on instances older than 17 while an unreported version still sends. The 404 ambiguity is disclosed. Loses a point only because the refusal/404 behavior is described at high density without a crisp ordering rule for the agent.

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 followed by return shape, then pitfalls, then cross-references — a sensible ordering. The pitfalls paragraph is long and nests several conditional cases, which is justified by the version-gating complexity but slightly heavier than needed.

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?

Covers the version-compatibility gate, the ambiguous 404, idempotency, per-user semantics, and the alternatives for reading state — everything an agent needs to invoke this correctly on a versioned instance. An output schema exists, and the description still summarizes the return for convenience.

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

Parameters3/5

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

Schema coverage is 100%, so both parameters are already fully documented in the schema, including the 'no toggle' warning. The description reinforces the state-vs-toggle framing but adds no syntax or sourcing detail the schema lacks. Baseline 3 is appropriate.

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 and resource (add/remove a project from the authenticated user's favorites) and immediately bounds the scope to per-user state. It explicitly disclaims two confusable neighbors ('not project status and not a work-package watcher'), so an agent can distinguish it from siblings without reading the schema.

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?

Gives a concrete trigger ('when the user asks to pin, star or favorite a project they work in') and names three alternatives with their distinct roles: list_projects(favorites_only=true), get_project, get_instance_info. The version pre-check path is spelled out rather than left implicit.

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

Deploy Server