Task-provider MCP tools

The built-in MCP server gives an agent one task interface for Glueprint boards and connected external issues. External calls use the credentials on the host running the session. Credentials are never MCP arguments or tool results.

Read tools

Read tools do not ask for approval.

Tool	Arguments	Returns
gp_task_sources	Optional force	Providers, source instances, authentication state, capabilities, hidden providers, and per-source errors.
gp_task_list	source, query, optional force	One task page with tasks, next_cursor, and truncated.
gp_task_get	source, task_id, optional force	One normalized task. Its allowed_next entries contain transition IDs accepted by gp_task_transition.
gp_task_search	sources, query	Pages from successful sources and an error entry for each failed source. sources is "all" or one source object.

Set force to true when the agent must bypass a retained read and ask the host again.

Write and start-work tools

Tool	Required arguments	Result data
gp_task_create	source, input	The created task.
gp_task_update	source, task_id, patch	The updated task.
gp_task_transition	source, task_id, transition_id	The task after the transition.
gp_task_comment	source, task_id, body	The created comment.
gp_task_start_work	source, task_id, project_id, agent_id, workspace, start	The linked work item, whether it started, and any provider follow-up warnings.

Calls that change an external provider require user approval. Starting work also requires approval. The approval card identifies the provider, instance, container, operation, target, and proposed changes. It does not include credentials.

Common source object

{
  "provider": "github",
  "instance_id": "github.com",
  "container_id": "acme/app"
}

Choose provider from the available providers returned by gp_task_sources. instance_id is required. container_id can be omitted or null only when the operation does not need a selected board, repository, project, or team.

Common query object

Every field is optional:

Field	Values
container	Provider container ID
preset	open, assigned_to_me, created_by_me, recently_updated, or all; default open
text	Provider text search
status_category	backlog, todo, in_progress, in_review, done, or canceled
status_ids	Array of provider-native status IDs
labels	Array of provider label IDs
cursor	The unchanged opaque value returned as next_cursor
limit	Integer from 1 through 50

Do not inspect or construct a cursor. Pass the returned value back with the same source and query.

Create and update shapes

gp_task_create requires input.container_id and input.title. It can also accept description, description_format (markdown, plain, or adf), priority_id, assignee_ids, label_ids, issue_type_id, and parent_id. Providers reject fields they do not support.

gp_task_update accepts a patch containing any supported combination of title, description (a string or null), priority_id, and label_ids.

Use the exact transition_id returned by gp_task_get. Provider transition IDs are scoped to the addressed task and source.

Start-work workspace

Choose one workspace shape:

{ "kind": "project_root" }

{ "kind": "existing_dir", "path": "/absolute/project/worktree" }

{ "kind": "new_worktree", "branch": "feature/issue-key", "base_ref": "main" }

For a new worktree, branch and base_ref can be omitted or null. start: true creates and starts the linked session with the provider task as context. start: false creates the linked work item without starting its agent.

Optional start-work arguments are name, prompt_override, permission_mode, collaboration_mode, model, and reasoning_effort.

Result envelope

Every task-provider tool returns a JSON envelope as text. A successful call has ok: true, a data value, and the resolved source when the operation is source-specific. A provider refusal has ok: false and an error with code, message, and optional details; the MCP result is marked as an error.

Write request identifiers are owned by Glueprint. An agent must not add one to tool input.

For the rest of the built-in server, see The built-in MCP server.