404 on work_items / milestones tools against self-hosted Plane v1.0.0 — SDK calls /work-items/ but instance exposes /issues/

[healdigital]

Summary

When using plane-mcp-server v0.2.8 against a self-hosted Plane Community Edition v1.0.0 instance (image artifacts.plane.so/makeplane/plane-backend:v1.0.0), every work_items / milestones tool returns HTTP 404 because the underlying plane-sdk calls /work-items/ and /milestones/ endpoints that don't exist on the v1.0.0 API surface — which still exposes the canonical /issues/ and (no) /milestones/.

Affected endpoints (404)

• create_work_item, list_work_items (project + workspace scope)
• retrieve_work_item, update_work_item, delete_work_item
• create_milestone, list_milestones
• get_workspace_features

Endpoints that DO work (legacy paths preserved)

• create_project, list_projects
• create_state, list_states
• create_label, list_labels
• create_module, list_modules
• list_cycles
• get_workspace_members

Reproduction

1. Self-host Plane CE v1.0.0 (Docker images artifacts.plane.so/makeplane/plane-{backend,frontend,proxy,admin,space,live}:v1.0.0)
2. Generate an API key (plane_api_xxx…)
3. Configure plane-mcp-server v0.2.8 with PLANE_API_KEY + PLANE_WORKSPACE_SLUG + PLANE_BASE_URL
4. Call any work_item tool → 404
5. Verify directly with curl:

# 200 ✓ — what Plane v1.0.0 exposes
curl -H "X-Api-Key: $PLANE_API_KEY" \
  "$PLANE_BASE_URL/api/v1/workspaces/$SLUG/projects/$PID/issues/"

# 404 ✗ — what the SDK calls
curl -H "X-Api-Key: $PLANE_API_KEY" \
  "$PLANE_BASE_URL/api/v1/workspaces/$SLUG/projects/$PID/work-items/"

Root cause (SDK source)

plane-sdk/plane/api/work_items/base.py:45 and following construct URLs like:

/workspaces/{slug}/projects/{pid}/work-items
/workspaces/{slug}/work-items/search
/workspaces/{slug}/work-items/advanced-search

These match the renamed UI endpoints in Plane Cloud / newer versions, but the publicly exposed REST API of Plane v1.0.0 CE still uses /issues/ (and does not expose milestones at all via REST).

Suggested fix

Either:

• Add a version-detection branch in plane-sdk that falls back to /issues/ when API returns 404 on /work-items/, or
• Document a compat env flag (PLANE_USE_LEGACY_ISSUES_ENDPOINT=1) for self-hosted v1.0.0 instances, or
• Pin the SDK URL pattern based on the Plane server version (which is queryable at /)

Workaround currently in production

Internal REST helper bypassing the MCP for work-items, hitting /issues/ directly:
https://github.com/healdigital/Paperclip/blob/main/companies/heal-sarl/scripts/plane-rest-helper.sh
(used to bootstrap 4 production projects with 44 work items today, all created successfully)

Environment

• Plane CE: v1.0.0 (self-hosted on Coolify)
• plane-mcp-server: v0.2.8 (via uvx)
• plane-sdk: v0.2.6
• Client: Claude Code (Anthropic Agent SDK)
• Date: 2026-05-18