NODEDC_TASKMANAGER_CODEXAPI/docs/MCP_TOOLS_CONTRACT.md

MCP Tools Contract

Last updated: 2026-05-14.

Position

The current Tasker / Plane fork does not expose a dedicated MCP server. It exposes REST endpoints and NODE.DC internal endpoints. The new module should expose MCP tools externally and translate those tool calls into validated Tasker adapter calls.

Codex should not call generic Tasker REST directly.

Current implementation status:

• Agent Gateway exposes /mcp as JSON-RPC over HTTP.
• Implemented MCP methods: initialize, ping, tools/list, tools/call.
• tools/list returns only tools allowed by the authenticated agent session scopes.
• tools/call uses the same product runtime as REST tool endpoints.
• Server-sent event streaming is intentionally not required for the first product slice.

Authentication

MCP clients authenticate to Agent Gateway with an opaque agent token.

Recommended transport options:

• HTTPS MCP endpoint for general clients;
• local stdio connector later if useful;
• REST fallback for non-MCP clients.

Current route:

POST /mcp

Required request headers for authenticated tool calls:

Authorization: Bearer <agent-token>
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2025-06-18

Token rules:

• token is opaque;
• server stores only token hash;
• token is scoped to one agent;
• token can be revoked immediately;
• token expires;
• owner blocked/annulled disables tokens.

Tool list

tasker_get_agent_instructions

Returns operating rules, allowed projects, card guide, and reporting expectations.

Required scope:

workspace:read

tasker_list_projects

Lists projects granted to the agent.

Required scope:

project:read

tasker_get_project_context

Returns project states, labels, members, and card-writing rules.

Required scope:

project:read

tasker_search_issues

Searches existing work items within granted projects.

Required scope:

issue:read

tasker_get_issue

Returns one issue with description, structured blocks, labels, state, assignees, and comments summary.

Required scope:

issue:read

tasker_create_issue

Creates a work item.

Required scope:

issue:create

Allowed fields:

project_id
name
description_html
detail_layout
state_id
priority
label_ids
assignee_ids
start_date
target_date
parent_id

Validation:

• project must be granted;
• state must belong to project;
• labels must belong to project;
• assignees must be active project members;
• detail layout must match NODE.DC structured block schema.

tasker_update_issue

Patches allowed issue fields.

Required scope:

issue:update

Allowed fields:

name
description_html
detail_layout
priority
start_date
target_date
parent_id

Deletion, archive, and project transfer are not allowed.

tasker_move_issue

Changes issue state and optional sort order.

Required scope:

issue:move

Allowed fields:

state_id
sort_order

Validation:

• target state must belong to the same project;
• cancelled/completed moves are allowed only if the grant permits them.

tasker_set_issue_labels

Sets or merges labels.

Required scope:

issue:label

Validation:

• labels must already exist in project for MVP;
• creating new labels can be added later under label:create.

tasker_assign_issue

Sets assignees.

Required scope:

issue:assign

Validation:

• assignees must be active project members;
• if the user asks to add a workspace member to the project, use tasker_add_existing_project_member first.

tasker_add_existing_project_member

Adds an existing workspace member to a granted project.

Required scope:

project:member:add_existing

Validation:

• target user must already be an active workspace member;
• target user role cannot exceed workspace role;
• launcher-managed workspace rules must be respected;
• the request should be traceable to an explicit human instruction or reporting policy.

tasker_append_comment

Adds a comment to an issue.

Required scope:

issue:comment

Allowed fields:

comment_html

tasker_update_structured_blocks

Replaces or patches NODE.DC structured blocks in detail_layout.

Required scope:

issue:structured_blocks:write

Supported blocks:

text
checker

Canonical key:

nodedc_structured_blocks

The tool should support high-level patch actions:

append_text_block
append_checker
update_checker_item
replace_blocks
append_implementation_note

tasker_start_work_session

Starts a reporting session for a project or issue.

Required scope:

issue:comment

This is mainly for enterprise reporting mode.

tasker_finish_work_session

Finishes a reporting session and appends summary/validation notes.

Required scope:

issue:comment
issue:structured_blocks:write

Idempotency

All write tools must accept:

idempotency_key

Agent Gateway stores result mapping and returns the prior result for duplicate keys.

Denied tools

These should not exist in MVP:

tasker_delete_issue
tasker_archive_issue
tasker_delete_comment
tasker_delete_label
tasker_delete_project
tasker_invite_workspace_member
tasker_raw_api_request

Instruction pack

tasker_get_agent_instructions should include the effective card guide. The local Codex setup file should instruct the agent to call this tool before planning Tasker changes.

Minimum instruction:

Before creating or updating Tasker cards, call tasker_get_agent_instructions.
Use Tasker for durable project planning, current architecture, planned architecture, stage checkers, implementation notes, and validation results.
Do not create multiple top-level cards for substeps of one product topic.
Do not delete or archive cards.
Do not operate outside granted projects.