MCP Architecture

[adamoutler]

Is this project open to a rearchitecture of the MCP server?

Currently, the Plane MCP server appears to be a direct replica of the underlying REST APIs. This forces the AI to act as a web browser making sequential CRUD requests, which is an anti-pattern for LLM tooling. It leads to high latency, increased surface area for reasoning errors, and severe context window exhaustion due to returning massive, non-useful JSON payloads.

The MCP server should be architected for expected AI interactions—abstracting multi-step workflows into single, intent-driven tool calls.

Problem Context: Current API-Replica Approach

Here are two examples of how the current 1:1 mapping breaks down in practice:

Scenario 1: Creating an Issue
Current workflow:

1. list_projects
2. AI reads, parses, and locates the project ID.
3. create_issue using project_id and new issue name.
4. Result: AI receives a massive JSON dump containing all the information it just submitted, burning context for no reason.

Proposed "AI Journey" workflow:

1. create_issue("WEBUI", "name of issue")
2. Result: AI receives a concise acknowledgment: {"id": "WEBUI-1", "success": true}

Scenario 2: Beginning Work on an Issue
Current workflow (High failure rate):

1. Attempt retrieve_work_item_by_identifier (Currently fails due to MCP bug).
2. Fallback to list_all_issues (Massive context burden).
3. AI parses to locate the issue ID.
4. list_projects -> locate project ID.
5. get_me -> locate user ID for assignment.
6. list_states -> locate "in-progress" state ID.
7. update_work_item(project_id, work_item_id, state, assignee)
8. Result: Another massive context dump of the entire issue.

Proposed "AI Journey" workflow:

1. get_item("WEBUI-1") -> returns essential context {"id":"WEBUI-1", "title":"...", "details":"..."}
2. start_work_on("WEBUI-1") -> server automatically handles the state transition, assignment to the active AI/user, and background lookups.
3. Result: {"id": "WEBUI-1", "success": true}

Proposed Architectural Solution

I recommend reworking the MCP to drastically reduce the testing surface area and optimize for semantic compression. Tools should be intent-based:

• project_info(project_metadata: true, workspaces: true, cycles: true)
  • Delivers all project and cycle metadata contextually in one call. Eliminates the need for multiple metadata lookups.
• create_issue(project_key, title, ...)
  • Creates an issue and returns only the newly generated ID and success status.
• list_issues(type: [basic | status | extended | details], filter: {...})
  • Provides token-optimized views of issues to prevent context flooding.
• get_issue(type: [basic | extended])
  • Provides only what is strictly required to work on the issue, or the full JSON if explicitly requested.
• update_issue(issue_key, ...)
  • Intent-driven updates.
• add_comment(issue_key, comment)
  • Simple append operation.
• manage_cycle(cycle_id, add_items: [], remove_items: [], name, description)
  • Batch operations for cycle management in a single tool call.

High-Friction Destructive Actions
To prevent AI hallucinations from causing data loss, destructive actions should be implemented as a 2-stage, high-friction process:

1. request_delete(key/cycle/project): Declares intent to delete and returns a warning with a request_id.
2. execute_delete(request_id, understanding_declaration, full_content_hash): The AI must explicitly echo back what it is deleting, making unintentional deletions virtually impossible.

[adamoutler]

I'm working on two ideas for this on my own private git right now. https://git.adamoutler.com/AI/plane-mcp-rework/src/branch/ai-journeys-rearchitecture

1. proposal/ - common "AI Journey" items up front and easily accessible (tier 1). Uncommon items contained within a single command that provides feedback, schema, and documentation just-in-tome.
2. proposal2_split/ - 2-MCPs an "AI Journey' mcp and a full-1:1 mapping MCP.

Comparing the two, Proposal revises the whole system, giving the AI a more workable MCP and a better AIX all together. Proposal2 is easier to implement and this auto-generated 1-api=1-mcp as a fallback retaining backward compatibility if the current token-wasting system is part of a fixed workflow.

[adamoutler]

I have implemented the intent-driven architecture proposed above, extensively tested, and am currently migrating my projects to use it. I would appreciate any feedback from the Plane developers or community members who want to test it.

This rework introduces a dedicated agent endpoint optimized specifically for LLM task execution utilizing what I call Friction Architecture, because not all tasks deserve the same level of friction. It does not affect the existing 1:1 http-api. Instead, it focuses the surface area strictly on work-related workflows, exposing the following streamlined tools:

🟢 kanban - Ready (7 tools)
  Tools:
  - mcp_kanban_begin_work
  - mcp_kanban_complete_work
  - mcp_kanban_create_ticket
  - mcp_kanban_read_ticket
  - mcp_kanban_search_tickets
  - mcp_kanban_transition_ticket
  - mcp_kanban_update_ticket

Resources & Testing

• Package page: plane-mcp-rework/latest
• Source Code: plane-mcp-rework
• Actions Build: View Actions
• Docker command: docker pull git.adamoutler.com/ai/plane-mcp-rework:latest
• Agent Context Example: View payload initialization and query

Setup
Because this provides a separate, intent-based endpoint, it can run directly alongside the original API. If your current MCP URL uses /mcp/http-api/api-key/mcp, you can duplicate your server configuration and simply change http-api to agent. For normal operation you can /mcp disable full_plane_http_api and enable when you need to perform some administrative tasks.

Example mcpServers configuration:

{
  "mcpServers": {
    "kanban": {
      "url": "https://example.com/mcp/agent/api-key/mcp",
      "headers": {
        "Authorization": "Bearer ${KANBAN_API_KEY}",
        "X-Workspace-slug": "${WORKSPACE_SLUG}"
      }
    },
    "full_plane_http_api": {
      "url": "https://example.com/mcp/http-api/api-key/mcp",
      "headers": {
        "Authorization": "Bearer ${KANBAN_API_KEY}",
        "X-Workspace-slug": "${WORKSPACE_SLUG}"
      }
    }
  }
}

Search is fully functional too!

Overall, I'm seeing less errors and enhanced productivity thus far.

[adamoutler]

Another benefit of this; The default MCP will not load in Antigravity by default

However the intent-based agent-journey MCP I'm working on loads with plenty room to spare.

[adamoutler]

Working in Google Antigravity (or VSCode)

[adamoutler]

While work is still in progress right now, I had my Gemini agent perform use and analysis of the plane and agent MCP servers. This is what it had to say: https://gemini.hackedyour.info/s/853719b5-ccc1-4041-8ed1-2009ed006494

Take note of the amount of errors. This is Gemini Pro 3.1 we're dealing with. Kanban interaction should be a minor thing the LLM does as a part of work, not a troubleshooting step all of its own.

The two MCPs work side-by-side. You can make two entries one for the http-api and one for the agent api.

This scales to lights-out factory work as well. The tentative procedure I'm working with is as follows:
CLI Mode - for Claude, Gemini CLI or Codex

1. Repo must be committed, in pristine state, and CI/CD for the commit is completed.
2. add a hook for both update-ticket(state:done) and complete_work and route the ticket contents & comments, and CI/CD results to a QA agent who requires absolute proof of completion (logs/screenshots)
3. Any QA comments are added to the ticket and the rejection notice if applicable.
4. disable commands matching regex curl .*my.plane.com.*

VSCode Mode - for VSCode, Antigravity, or similar

1. The above checks are placed into a shell script. The shell script is set to chmod 755 chown root
2. disable commands matching regex curl .*my.plane.com.*
3. The MCP endpoints update_ticket and complete_work are disabled

The agent's primary goal is always to complete the ticket. Using the above as basic frameworks, you can place an agent on a cron job or allow it to run to completion.