The plane-selfhost-mcp server provides tools for managing a self-hosted Plane project management instance via X-API-Key authentication:
Verify authentication (get_user_me): Check that your API key and connection are working by retrieving the currently authenticated user.
List projects (list_projects): List all projects in the configured workspace to resolve project IDs.
List issues (list_project_issues): List all issues within a specific project.
Create issues (create_issue): Create a new issue with a title, and optionally set state, priority, and HTML description.
Update issues (update_issue): Modify existing issue fields including name, state, priority, labels, assignees, target date, HTML description, and parent (for parent-child hierarchy).
Comment on issues (add_issue_comment): Add an HTML-formatted comment to an issue.
List states (list_states): List available workflow states for a project.
List labels (list_labels): List existing labels for a project.
Create labels (create_label): Create new labels within a project.
Pages (experimental): List, create, and update project pages — requires a Plane edition/build with API-key-compatible Pages endpoints.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@plane-selfhost-mcp list all my projects"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Custom MCP server for self-hosted Plane instances that require X-API-Key authentication instead of Authorization: Bearer.
This project exists because the official Plane MCP flow did not work reliably against this self-hosted environment. This server talks directly to the Plane REST API, exposes a small focused MCP toolset, and is designed to be consumed from OpenCode.
Connects to a self-hosted Plane workspace with X-API-Key
Exposes Plane operations as MCP tools over stdio
Supports project discovery, issue listing, issue creation, issue updates, parent-child hierarchy updates, comments, workflow state lookup, and project label management
Includes experimental/diagnostic project page tools for Plane editions/builds that expose API-key-compatible Pages endpoints
Works with OpenCode through a local MCP server entry such as plane-selfhost
Related MCP server: plane-mcp-server
The official Plane MCP server uses Authorization: Bearer <token>. In this self-hosted setup that produced auth failures, while direct API calls with X-API-Key worked correctly.
So the right move was NOT to keep fighting the wrong auth model. The right move was to build a thin MCP wrapper around the API behavior that the real instance actually accepts.
Python 3.10+
A reachable self-hosted Plane instance
A Plane API key with workspace access
The Plane workspace slug
cd plane-selfhost-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"Preferred path: copy .env.example to a project-root .env file so OpenCode and local commands can share one source of truth.
cp .env.example .envThen edit .env with your real values.
At startup the MCP loads .env automatically, then reads the real process environment on top of it. That means explicit environment variables still win when you need a one-off override.
If you prefer, you can still export the variables directly instead of using .env.
The server fails fast with a clear error if any required variable is missing from both sources.
source .venv/bin/activate
python -m plane_selfhost_mcpsource .venv/bin/activate
plane-selfhost-mcpAfter installing the package, you can use the local Makefile instead of manually activating the virtual environment:
make help # list available targets
make install # install the package and dev dependencies in .venv
make run # run the MCP server (sources .env automatically if present)
make smoke-test # verify config loads (sources .env automatically if present)
make whoami # print the authenticated Plane user (sources .env automatically if present)
make list-projects # list workspace projects (sources .env automatically if present)
make list-states # list workflow states for a project (requires PROJECT_ID=...)
make create-test-issue # create a test issue in a project (requires PROJECT_ID=... TITLE=...)
make move-issue # move an issue to a target state (requires PROJECT_ID=... ISSUE_ID=... STATE_ID=...)
make comment # add an HTML/plain comment to an issue (requires PROJECT_ID=... ISSUE_ID=... COMMENT="...")
make test # run pytestFree-form values such as TITLE and COMMENT are passed to the inline Python scripts through environment variables, so quotes and special characters do not break the command.
make run, make smoke-test, make whoami, make list-projects, make list-states, make create-test-issue, make move-issue, and make comment will source a .env file in the project root if one exists, so you do not need to export variables manually every time.
Add this MCP server to your OpenCode config:
{
"mcp": {
"plane-selfhost": {
"type": "local",
"enabled": true,
"command": [
"/absolute/path/to/plane-selfhost-mcp/.venv/bin/python",
"-m",
"plane_selfhost_mcp"
]
}
}
}Recommended setup for OpenCode: keep Plane credentials in the repo's .env file and let the MCP load them automatically at startup.
Use the MCP env block only when you intentionally want OpenCode to override the .env values for that process.
Replace /absolute/path/to/plane-selfhost-mcp/.venv/bin/python with the Python executable from your own local virtual environment.
After updating OpenCode config, restart OpenCode. MCP config is not hot-reloaded.
Tool | What it does | Typical use |
| Returns the authenticated Plane user | Verify auth/config works |
| Lists projects in the configured workspace | Resolve a target project before issue work |
| Lists issues for a project | Find an issue before updating it |
| Lists labels for a project | Resolve label IDs or inspect available labels |
| Experimentally lists pages for a project when the Plane edition/build exposes API-key-compatible Pages endpoints | Diagnose page endpoint availability or inspect pages on supported builds |
| Experimentally creates a page when the Plane edition/build exposes API-key-compatible Pages endpoints | Add rich project documentation only on supported builds |
| Experimentally updates page fields when the Plane edition/build exposes API-key-compatible Pages endpoints | Edit page metadata only on supported builds |
| Creates a label in a project | Add a new label before assigning it to issues |
| Creates a new issue | Add a task/bug/story in Plane |
| Updates issue fields | Move states, rename, reprioritize, assign, relabel |
| Sets an issue's parent in Plane's hierarchy | Create parent-child issue/work-item structure, not dependencies |
| Adds an HTML comment to an issue | Leave progress notes or audit comments |
| Lists workflow states for a project | Resolve initial/done state IDs before transitions |
This MCP is intentionally simple. The safest usage flow is:
Call get_user_me to prove the connection.
Call list_projects to resolve the target project_id.
If the action depends on workflow placement, call list_states.
For labels, call list_project_labels first or create them with create_project_label.
For pages, first confirm your Plane edition/build exposes API-key-compatible Pages endpoints; on Plane Community v1.3.1, these tools are expected to fail diagnostically.
Create or update issues and supported pages only after resolving IDs from live responses.
Treat responses as successful only when the MCP payload returns ok: true.
Do not invent project_id, issue_id, or state values.
Label assignment accepts existing label UUIDs or names, but names are resolved against the project's existing labels before the request is sent.
Missing label names are rejected locally with a clear error. Issue tools do not auto-create labels.
Use create_project_label explicitly when you want to create a new label.
Use description_html and comment_html for rich text fields.
Plane Community v1.3.1 exposes project pages only through web-app/session-auth routes under /api/workspaces/{workspace_slug}/projects/{project_id}/pages/. As tested, API-key-compatible Pages API routes are not available in Community.
Page tools are experimental/diagnostic unless the target Plane edition/build exposes API-key-compatible Pages endpoints. On Community v1.3.1, they are expected to fail diagnostically rather than provide functional Pages support.
Existing project, issue, label, and state tools continue to use public /api/v1/workspaces/... routes with X-API-Key.
External Pages API access with API-key authentication appears to be Commercial/Cloud functionality, not Plane Community behavior. The MCP intentionally does not implement browser/session auth.
Use set_issue_parent for parent-child hierarchy only. It calls Plane's work-items API with parent; it does not create dependency relations such as blocking or blocked-by.
Self-hosted Plane in this setup expects X-API-Key, not bearer auth.
If auth fails, debug credentials first; do not assume the API path is wrong.
This repository includes a shared plane-mcp skill artifact that another user can copy into their own OpenCode skills setup.
Skill location in this repository: skills/plane-mcp/SKILL.md
The repository does not auto-register that skill for anyone. OpenCode will only use it after each user copies or registers it in their own local OpenCode configuration.
The plane-mcp skill exists so agents follow the correct operational contract every time instead of improvising.
It teaches the agent to:
target the custom plane-selfhost-mcp
verify config and auth first
resolve IDs from live Plane responses
use list_states before state transitions
stop and surface errors when the MCP payload returns ok: false
Clone this repository and install the MCP package.
Configure the repository root .env file with real Plane credentials.
Add the MCP server entry shown in OpenCode integration to your own OpenCode config.
Copy skills/plane-mcp/SKILL.md into your own OpenCode skills directory, or register it from your own OpenCode setup.
Restart OpenCode after registering the skill.
The .env-first recommendation stays the same: keep credentials in the repository root .env file by default, and use the MCP env block only for intentional per-process overrides.
source .venv/bin/activate
python -c "from plane_selfhost_mcp.config import load_config; print(load_config())"source .venv/bin/activate
python -c "
import asyncio
from plane_selfhost_mcp.config import load_config
from plane_selfhost_mcp.client import PlaneClient
async def main():
cfg = load_config()
client = PlaneClient(cfg)
try:
print('ME:', await client.get_user_me())
print('PROJECTS:', await client.list_projects())
finally:
await client.close()
asyncio.run(main())
"Expected result:
get_user_me returns the authenticated user
list_projects returns workspace projects
Plane issue mutations expect label UUIDs, but this MCP now resolves existing project label names for you before sending the API request.
Deterministic behavior:
create_issue and update_issue accept labels as a list of existing label UUIDs and/or existing label names.
Name resolution checks the target project's labels first.
Exact name matches win first.
If only one case-insensitive match exists, it is accepted.
If a name does not exist, the MCP fails before sending the issue mutation.
If case-insensitive matching is ambiguous, the MCP fails and tells you to use a UUID.
Labels are only created through create_project_label.
Example flow:
Call list_project_labels for the target project.
If the label is missing, call create_project_label.
Call create_issue or update_issue with either the label UUID or the label name.
Live verification status:
After restarting OpenCode so it reloaded the MCP config, we verified live MCP issue creation with labels against the self-hosted Plane instance.
The successful path was: restart OpenCode -> resolve the project -> ensure the label already exists (or create it first) -> call create_issue with label names.
make testOr, with the virtual environment activated:
pytestTopic | Value |
Python |
|
Entry point |
|
Runtime deps |
|
Test deps |
|
src/plane_selfhost_mcp/
├── client.py # Plane REST client
├── config.py # env loading and validation
├── server.py # MCP tool registration and stdio server
└── __main__.py # python -m entrypoint
tests/
└── test_client.py # HTTP client testsIf you see a runtime error about missing PLANE_BASE_URL, PLANE_API_KEY, or PLANE_WORKSPACE_SLUG, check the project-root .env file first, then check whether the MCP process is receiving any explicit env overrides.
Plane received no credentials. Check whether .env exists in the project root, then check whether the MCP env block is actually being passed.
For project page tools specifically, a 401 Unauthorized response can also mean the route exists but Plane rejected the current X-API-Key auth for pages. The self-hosted pages endpoint may require session, JWT, cookie auth, or an API token with pages support. This MCP intentionally does not support browser/session auth yet.
Current self-hosted stable finding: project pages are exposed through Plane's web-app/session-auth route family, not through the public API-key route family used by the rest of this MCP. Do not configure browser cookies or session tokens as a workaround unless Plane documents that auth flow as a stable automation contract.
The credential reached Plane but the API key is invalid or lacks access.
Verify the workspace slug and call list_projects before attempting issue operations.
If list_project_pages, create_project_page, or update_project_page returns 404 while project and issue tools work, verify that the self-hosted Plane pages routes are available under /api/workspaces/{workspace_slug}/projects/{project_id}/pages/ rather than the v1 prefix. Existing project, issue, label, and state tools still use /api/v1/workspaces/.... Also confirm the API key includes projects.pages:read or projects.pages:write, because Plane may mask missing page scopes as 404.
MIT
Add a comment to an issue.
| Name | Required | Description | Default |
|---|---|---|---|
| issue_id | Yes | Plane issue UUID or identifier. | |
| project_id | Yes | Plane project UUID or identifier. | |
| comment_html | Yes | HTML comment body. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It indicates a write operation (add), but lacks details on permissions, side effects, or idempotency. Insufficient for safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, clear sentence with no filler or redundant information. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema is provided, and the description omits important context like return value, error handling, or prerequisites. For a simple mutation tool, more detail is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description adds no additional meaning beyond parameter names. Baseline 3 is appropriate as the schema already documents all three parameters adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (add) and resource (comment to an issue). It distinguishes from sibling tools like create_issue or list_issues, though it could be more specific about scope (e.g., 'to an existing issue').
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. No context about prerequisites (e.g., issue must exist) or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new issue inside a project.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Issue title. | |
| state | No | Optional state UUID to assign. | |
| priority | No | Optional priority (e.g. urgent, high, medium, low). | |
| project_id | Yes | Plane project UUID or identifier. | |
| description_html | No | Optional HTML description. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavioral traits. It only says 'create', but no details on side effects (e.g., notifications, triggers), required permissions, or return values. Lacks transparency for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is concise but overly terse. Lacks structure (e.g., no bullet points or examples) and front-loads critical info moderately. Efficiency is good but at cost of clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 5 parameters, 2 required, no output schema, and no annotations, the description is incomplete. It doesn't mention mandatory vs optional fields, how to obtain required IDs, or what happens after creation. A 3-param sibling adds complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so description adds minimal value beyond parameter names and types. It does not elaborate on relationships or usage patterns (e.g., how state UUID is obtained). Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create a new issue inside a project' clearly states the action and resource. It distinguishes from sibling tools like update_issue or list_project_issues, but could be more specific about scope (e.g., in which project).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives (e.g., add_issue_comment) or prerequisites like required permissions. Missing context for effective selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the currently authenticated Plane user.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description accurately implies a read operation with no side effects. It assumes authentication is required, which is reasonable for a user endpoint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no superfluous words, perfectly front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with no parameters and no output schema, the description fully covers what the agent needs to know.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters, schema coverage is 100%. Description does not add parameter-level detail, but given zero parameters, the baseline score of 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'return' and resource 'currently authenticated Plane user', uniquely distinguishing it from siblings that deal with issues, projects, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is clear: it returns the current user. No explicit when/not or alternatives are needed given the simplicity and zero parameters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List issues for a given project.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Plane project UUID or identifier. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behavioral traits. It only states basic purpose, omitting details like read-only nature, pagination, error handling, or whether it returns all issues or supports filters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no extraneous information. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one required parameter and no output schema, the description is minimally adequate but lacks details on output format, pagination, or filtering. Additional context would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter project_id, which has a description. The tool description adds no additional meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (List), resource (issues), and scope (for a given project). It distinguishes from siblings like create_issue and list_projects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives like list_projects or when not to use it. No context on prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all projects in the configured Plane workspace.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only states 'List all projects,' giving no details about authorization needs, rate limits, or side effects. The behavior is implied but not explicitly described.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that immediately conveys the tool's purpose. Every word is necessary, and there is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with no output schema and no parameters, the description is minimally adequate. It names the resource but does not elaborate on what constitutes a 'project' or any filtering options. Given the low complexity, it meets the minimum bar.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage. Since there are no parameters, the description does not need to add parameter information, earning a baseline score of 4 as per guidelines.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all projects in the configured Plane workspace,' specifying the verb (list) and resource (projects). It distinguishes from siblings like 'list_project_issues' which operates on a different resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as 'list_project_issues' or 'get_user_me'. The description does not mention context, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List workflow states for a project.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Plane project UUID or identifier. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavior. It only states it 'lists' states, with no mention of read-only nature, pagination, sorting, or potential side effects. Lacks detail for a complete behavioral profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words. However, it could be slightly more structured or include an example, but remains appropriately concise for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with one parameter and no output schema, the description is minimally complete. However, it does not explain what workflow states are or how the response is structured, which might be needed for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already describes project_id. Description adds no additional meaning beyond the schema, meeting baseline expectation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List') and the resource ('workflow states for a project'). It is specific and distinctly separates the tool from sibling tools, none of which list states.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. The description does not mention any preconditions, exclusions, or compare to similar tools like list_project_issues or list_projects.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update mutable fields of an existing issue.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| state | No | ||
| labels | No | ||
| issue_id | Yes | Plane issue UUID or identifier. | |
| priority | No | ||
| assignees | No | ||
| project_id | Yes | Plane project UUID or identifier. | |
| target_date | No | ISO date string, e.g. 2026-07-03. | |
| description_html | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description should disclose behavioral traits like partial update behavior, idempotency, or error conditions. It only says 'update mutable fields' without details on side effects or required permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words, but it lacks sufficient detail. Conciseness is not an excuse for missing essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (9 parameters, no output schema, no annotations), the description is severely lacking. It does not explain return values, error handling, or the effect of partial updates, making it inadequate for reliable tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 33% schema description coverage, the description should compensate by explaining key parameters. It does not add any parameter information beyond the schema, leaving most parameters (name, state, labels, priority, assignees, description_html) unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates mutable fields of an existing issue, which distinguishes it from create_issue (creation) and list_project_issues (listing). However, it could be more specific about which fields are mutable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, such as when to use create_issue for new issues or list_project_issues for reading. No prerequisites or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool has a clearly distinct purpose: creating, updating, listing issues, listing projects, states, adding comments, and getting the current user. No overlaps.
All tools use snake_case with a consistent verb_noun pattern (e.g., list_projects, create_issue, update_issue). Even 'get_user_me' fits the pattern.
Seven tools is well-scoped for a project management server, covering essential operations without being too sparse or excessive.
Covers CRUD for issues and listing of projects and states. Minor gaps: missing delete issue, single issue retrieval, and user management beyond current user.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Search, read and create Linear issues, projects, teams and cycles.
AI-native project management for tasks, docs, collaboration, and agents.
Agent-complete, permission-scoped product operations for Priorify workspaces.
Shortcut project management. Create, update, search stories and manage workflows.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/nicolasegpla/plane-selfhost-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
