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.

[adamoutler]

I pushed my image to docker hub.
docker pull adamoutler/plane-mcp-server:ai-journeys-rearchitecture

It functions exactly like the original, but you can swap http-api for agent and get the reduced set of MCP "macros" which reduces error rates, reduces token count, and is overall faster.

Average agentic work cycle:
Me: Pick out some tickets from backlog you feel may be easiest to work on, create a cycle and begin work.
Agent:

• search_tickets("states": ["Backlog"])
• begin_work(["TEST-1", "TEST-2", "TEST-3"],"Phase 1")
• work happens...
• read_ticket("TEST-1")
• complete_work("TEST-1")

Average ticket creation:
Me: Whenever I foo, I can't bar except when I baz
Agent:

• search_tickets("foo")
• create_ticket( "project":"help") (help replaces get project info, cycle, tags, and provides all the necesities)
• create_ticket( "project":"test", "bar issue", "user states...")

It's very efficient, prone to success, and human readable! Patch coming soon. It's been two weeks and nobody has responded to this so Ill assume the devs are all asleep.

I honestly can't stress enough how much better the response from the AI is with an easy kanban system. I think before the context all went to kanban. Now it's going to the work.

[adamoutler]

Feeback Request

This is the only place I've currently posted about this project. I published to dockerhub yesterday so that I could test it properly. After only 24hours, there are 300 downloads and, I've yet to hear a peep. Either it works well and many people are already using it, or it doesn't work and I'm letting a bunch of people down.

[oscarvale-devoteam]

This is very interesting, I've had the same idea for a while because of the bloat. Looking forward to the progress :)

[adamoutler]

@oscarvale-devoteam it's done. you can use it right now, here https://hub.docker.com/repository/docker/adamoutler/plane-mcp-server/general

You want the agent version. Don't go for the latest or the emojification versions.

docker pull adamoutler/plane-mcp-server:plane-agent

I've been performing further token reducing experiments with the MCP and trying to transition to a different, ULTRA-LOW token use emoji format. The idea is to provide a map of keys in single-token emoji format, once in a help message, and then reuse those single tokens throughout the entire rest of the messages.

Here you can see some A/B testing of "Agent" versus "Emojification" versions of the reduced agent MCP. To orient you to these screenshots; I'm using Gemini CLI within my Gemini WebUI web-based terminal app from my phone (and context size is important on a phone). Here you can see the Gemini agent using agent MCP, then uv-local (emojification) MCP.

The agent concluded that agent was superior. I was super stoked about reducing context and making an API that was both human and machine readable. However, my agent stated he didn't like it. He wanted named fields... so my next idea is to reduce context by converting JSON into yaml

so

{
    "name": "Agent Test Ticket",
    "priority": "none",
    "assignees": [],
    "key": "TEST-87"
}

can become a yaml version:

name: Agent Test Ticket
priority: none
assignees:
key: TEST-87

This is something I will work on soon. I just want to ensure that the final ticket works right.

If you want something right now - I recommend using this drop-in replacement for plane-mcp-server

adamoutler/plane-mcp-server:plane-agent

https://git.adamoutler.com/AI/plane-mcp-server/src/branch/plane-agent

[adamoutler]

I really recommend using this. If for no other reason - SEARCH WORKS!

Here's an A/B testing shot showing search.

[adamoutler]

The emojification MCP failed - 2-out-of-3 LLMs say it sucks.

The Emoji interface is an experiment, based on Agent interface, and taking it further. Goals of this project are as follows:

1. Reduce context by removal of json boilerplate (quotes, spaces, brackets, braces, escape characters).
2. Reduce context by replacement of multi-token words with single-double-token emoji.
3. Provide templated responses with fallback of json for unrecognized responses or "full" LOD.
4. Create an interface that is both human and AI readable when displayed while providing maximum agent readability.
   This plan failed A/B testing with Gemini3.1/ChatGPT5.2/Claude 4.6Opus, citing concerns about user emoji being potentially confusing,not having clear deliniated structures, and the need to check the reference table.

• Gemini 3.1 Pro Preview: Prefers Agent
• ChatGPT 5.2: Prefers Agent
• Claude 4.6 Opus: Prefers Emojification

You can see the recorded results here https://hackedyour.info/raw/5nzi6dTp2xFD6zBt
if you have Claude and would like to try Emojification, it's availalbe here https://hub.docker.com/repository/docker/adamoutler/plane-mcp-server/tags/emojification/

It's still better than the stock Plane http mcp, but agent is better than emojification. I have one more to try - yaml-agent.

[adamoutler]

Agent JSON vs Agent YAML vs Agent Emoji — Fair Comparison

• Plane Default MCP — 108 CRUD tools, returns every field from the Plane API verbatim.
• Agent JSON — 7 intent-driven tools with field reduction, progressive LOD, and macro workflows. Baseline for this comparison.
• Agent YAML — Agent API with YAML output: 2-space indent, flow-style lists, empty-field stripping.
• Agent Emoji — Agent API with emoji-encoded output: state/priority as glyphs, compressed key-value format.

Why Format Matters

The default Plane MCP server returns 1,925 chars for a single project. This is what the agent sees for one entry in a project list:

{
    "id": "0a5ca86e-9393-4b61-ac3b-018b95f711fd",
    "is_favorite": false,
    "sort_order": 65535.0,
    "member_role": 20,
    "anchor": "1ee51fa76028483ebab85af0149d8ebf",
    "members": [
        "dca60191-120a-46f8-8e63-3e9099866f38"
    ],
    "cover_image_url": "https://images.unsplash.com/photo-1691230995681-480d86cbc135?auto=format&fit=crop&q=80&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D&w=870&q=80",
    "inbox_view": false,
    "next_work_item_sequence": 67,
    "created_at": "2026-03-20T17:41:05.248929-04:00",
    "updated_at": "2026-04-13T17:04:11.199613-04:00",
    "deleted_at": null,
    "name": "Plane Agent MCP",
    "description": "This is the plane MCP \"Agent\" MCP...",
    "description_text": null,
    "description_html": null,
    "network": 2,
    "identifier": "AGENT",
    "emoji": null,
    "icon_prop": null,
    "module_view": true,
    "cycle_view": true,
    "issue_views_view": true,
    "page_view": true,
    "intake_view": false,
    "is_time_tracking_enabled": false,
    "is_issue_type_enabled": false,
    "guest_view_all_features": false,
    "cover_image": "https://images.unsplash.com/photo-1691230995681-480d86cbc135?auto=format&fit=crop&q=80&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D&w=870&q=80",
    "archive_in": 0,
    "close_in": 0,
    "logo_props": {
        "emoji": {
            "url": "https://cdn.jsdelivr.net/npm/emoji-datasource-apple/img/apple/64/1f447.png",
            "value": "128071"
        },
        "in_use": "emoji"
    },
    "archived_at": null,
    "timezone": "UTC",
    "external_source": null,
    "external_id": null,
    "created_by": null,
    "updated_by": "dca60191-120a-46f8-8e63-3e9099866f38",
    "workspace": "b961ca95-70ec-4a56-b868-954e0df19a95",
    "default_assignee": null,
    "project_lead": null,
    "cover_image_asset": null,
    "estimate": null,
    "default_state": null
}

The Agent API reduces this to 255 chars — an 84% reduction — by stripping UUIDs, cover images, view flags, and null fields:

{"project_slug":"AGENT","name":"Plane Agent MCP","description":"This is the plane MCP \"Agent\" MCP...","states":["Backlog","Todo","In Progress","Done","Cancelled"],"labels":["workout","test","context-optimization","enhancement","bug","concepts","admin"]}

This document compares three output formats for the Agent API to determine if further savings are possible beyond field reduction.

All servers hit the same Plane workspace (plane-mcp) and return the same data.

Tool Call	JSON (ref)	YAML	Emoji
search_tickets help	901	793 (-12%)	575 (-36%)
search_tickets results (3)	411	345 (-16%)	151 (-63%)
read_ticket (standard)	126	85 (-33%)	41 (-67%)
create_ticket	22	17 (-23%)	51 (+132%)
update_ticket	82	71 (-13%)	37 (-55%)
begin_work	132	125 (-5%)	117 (-11%)
complete_work	98	86 (-12%)	43 (-56%)
error (traceback)	1565	1798 (+15%)	N/A†

†Emoji falls through to raw JSON on errors.

Aspect	JSON	YAML	Emoji
Machine-parseable	✅ Native	✅ Standard parser	⚠️ Custom parser needed
Data preserved	✅ All fields	✅ All (empties stripped)	✅ All (v2, emoji-encoded)
Cursor/pagination	✅ next_cursor:	✅ next_cursor:	✅ ⏭️3:1:0
State/Priority	Text ("Done")	Text (Done)	Emoji (🟢➖)
Error detail	✅ Full trace	✅ Full trace	❌ Falls through
A/B test result	Baseline	Pending	❌ Failed

• plane-kanban → remote JSON server
• uv-local (yamlized) → local YAML branch
• uv-local (emojification) → local Emoji branch (v2, data-complete)

---

1. search_tickets (project_slug='help')

agent-json search_tickets — 901 chars

{"projects":[{"project_slug":"TEST","name":"test","description":"","states":["Backlog","Todo","In Progress","Done","Cancelled","delayed"],"labels":["Workout Label","agent-test","review","qa","workout","test","test issue","performance","backend","enhancement","security","bug"]},{"project_slug":"AGENT","name":"Plane Agent MCP","description":"This is the plane MCP \"Agent\" MCP...","states":["Backlog","Todo","In Progress","Done","Cancelled"],"labels":["workout","test","context-optimization","enhancement","bug","concepts","admin"]},{"project_slug":"EMOJI","name":"Emojification","description":"The Emoji interface is an experiment...","states":["Backlog","Todo","In Progress","Done","Cancelled"],"labels":[]},{"project_slug":"YAML","name":"YAML","description":"The YAML","states":["Backlog","Todo","In Progress","Done","Cancelled"],"labels":[]}],"priorities":["urgent","high","medium","low","none"]}

agent-yaml search_tickets — 793 chars

projects:
- project_slug: TEST
  name: test
  states: [Backlog, Todo, In Progress, Done, Cancelled, delayed]
  labels: [Workout Label, agent-test, review, qa, workout, test, test issue,
           performance, backend, enhancement, security, bug]
- project_slug: AGENT
  name: Plane Agent MCP
  description: "This is the plane MCP \"Agent\" MCP..."
  states: [Backlog, Todo, In Progress, Done, Cancelled]
  labels: [workout, test, context-optimization, enhancement, bug, concepts, admin]
- project_slug: EMOJI
  name: Emojification
  description: "The Emoji interface is an experiment..."
  states: [Backlog, Todo, In Progress, Done, Cancelled]
- project_slug: YAML
  name: YAML
  description: The YAML
  states: [Backlog, Todo, In Progress, Done, Cancelled]
priorities: [urgent, high, medium, low, none]

agent-emoji search_tickets — 575 chars

📁TEST(test) 🔄Backlog,Todo,In Progress,Done,Cancelled,delayed 🏷️Workout Label,agent-test,review,qa,workout,test,test issue,performance,backend,enhancement,security,bug
📁AGENT(Plane Agent MCP) 🔄Backlog,Todo,In Progress,Done,Cancelled 🏷️workout,test,context-optimization,enhancement,bug,concepts,admin
📁EMOJI(Emojification) 🔄Backlog,Todo,In Progress,Done,Cancelled
📁YAML(YAML) 🔄Backlog,Todo,In Progress,Done,Cancelled 🏷️test
⚡urgent,high,medium,low,none

Field Definitions:
Priority: 🚨urgent ⏫high 🔼medium 🔽low ➖none
Status: ⚫Backlog 🟣Todo 🔵In Progress 🟢Done 🔴Cancelled 🟡delayed

---

2. search_tickets (project=AGENT, limit=3, lod=summary)

agent-json search_tickets — 411 chars

{"results":[{"name":"[uv-local] Response shape test","priority":"none","state":"Done","assignees":[],"issue_key":"AGENT-66"},{"name":"[uv-local Workout] create_ticket test","priority":"none","state":"Cancelled","assignees":[],"issue_key":"AGENT-65"},{"name":"[A-B Test] Agent Ticket Creation","priority":"none","state":"Done","assignees":[],"issue_key":"AGENT-64"}],"next_cursor":"3:1:0","prev_cursor":"3:-1:1"}

agent-yaml search_tickets — 345 chars

results:
- name: '[uv-local] Response shape test'
  priority: none
  state: Done
  issue_key: AGENT-66
- name: '[uv-local Workout] create_ticket test'
  priority: none
  state: Cancelled
  issue_key: AGENT-65
- name: '[A-B Test] Agent Ticket Creation'
  priority: none
  state: Done
  issue_key: AGENT-64
next_cursor: '3:1:0'
prev_cursor: 3:-1:1

agent-emoji search_tickets — 151 chars

🟢➖AGENT-66 [uv-local] Response shape test
🔴➖AGENT-65 [uv-local Workout] create_ticket test
🟢➖AGENT-64 [A-B Test] Agent Ticket Creation
⏭️3:1:0
⏮️3:-1:1

---

3. read_ticket (AGENT-66, standard LOD)

agent-json read_ticket — 126 chars

{"issue_key":"AGENT-66","name":"[uv-local] Response shape test","description":"","priority":"none","labels":[],"state":"Done"}

agent-yaml read_ticket — 85 chars

issue_key: AGENT-66
name: '[uv-local] Response shape test'
priority: none
state: Done

agent-emoji read_ticket — 41 chars

🟢➖AGENT-66 [uv-local] Response shape test

---

4. create_ticket (YAML project)

agent-json create_ticket — 22 chars

{"issue_key":"YAML-1"}

agent-yaml create_ticket — 17 chars

issue_key: YAML-2

agent-emoji create_ticket — 51 chars

✅ Created YAML-4: [emoji-v2] Format comparison test

---

5. update_ticket (append text)

agent-json update_ticket — 82 chars

{"issue_key":"YAML-1","status":"success","message":"Ticket updated successfully."}

agent-yaml update_ticket — 71 chars

issue_key: YAML-2
status: success
message: Ticket updated successfully.

agent-emoji update_ticket — 37 chars

✅ Ticket YAML-4 updated successfully.

---

6. begin_work

agent-json begin_work — 132 chars

{"status":"success","details":{"YAML":"Processed 1 tickets. Note: Cycles are disabled for this project, skipped cycle assignment."}}

agent-yaml begin_work — 125 chars

status: success
details:
  YAML: 'Processed 1 tickets. Note: Cycles are disabled for this project,
    skipped cycle assignment.'

agent-emoji begin_work — 117 chars

✅ YAML: Processed YAML-4 - Processed 1 tickets. Note: Cycles are disabled for this project, skipped cycle assignment.

---

7. complete_work

agent-json complete_work — 98 chars (projected)

{"name":"[uv-local] Format comparison test","priority":"none","state":"Done","issue_key":"YAML-2"}

agent-yaml complete_work — 86 chars

name: '[uv-local] Format comparison test'
priority: none
state: Done
issue_key: YAML-2

agent-emoji complete_work — 43 chars

✅🟢➖YAML-4 [emoji-v2] Format comparison test

---

8. Error formatting (HTTP 429)

agent-json error — 1565 chars

{"error":"Error executing tool 'read_ticket': Failed to retrieve ticket 'AGENT-64': HTTP 429...stack trace..."}

agent-yaml error — 1798 chars

error: |
  Error executing tool 'read_ticket': Failed to retrieve ticket 'AGENT-64': HTTP 429...
  ...stack trace...

agent-emoji error — N/A

Falls through to raw JSON on errors (no custom error formatting).

9. Further testing required

I will perform an A-B test on the JSON/YAML formats soon and report results.

[adamoutler]

One more table. Total size savings for each formatting message when reading a ticket.

Format	Size (Chars)	Total Compression (vs Baseline)
Baseline	1,925	0%
JSON	126	-93.4%
YAML	85	-95.5%
Emoji	41	-97.8%

Emoji is tiny because it uses a map of emoji. A whole issue can be represented as such:

🟢➖AGENT-66 [uv-local] Response shape test

This type of compression is possible because the emoji carry semantic value

type	representation
Emoji	🟢
Yaml	state: Done
JSON	,"state":"Done"

I found an error during my previous A-B where I was not providing the table to the LLMs so I will need to perfrom an A-B-C test.

[adamoutler]

I'm not saying there's 0-error rate using the Agent API. I have observed the Gemini Agent fail to use the Agent API one time and it was today. In the middle of this block of issue creations there is a single error:

it then corrected the problem.