MCP Tools

UpliftPM exposes a Model Context Protocol (MCP) server so AI clients like ChatGPT, Claude, Cursor, and Codex can read and act on your projects. Tools run as the signed-in user and respect all project permissions.

Connect a client
Server URL
/mcp
Transport

MCP Streamable HTTP (spec 2025-06-18).

Auth

OAuth 2.1 with dynamic client registration. Your MCP client opens a UpliftPM consent page; approve it once and the client receives a user-scoped token. All tool calls run under that user's row-level security.

Required headers (POST)
Content-Type: application/json
Accept: application/json, text/event-stream
Authorization: Bearer <access_token>

Available tools

list_projects
Read-only

List all UpliftPM projects the signed-in user can access (as owner or member).

Parameters

No parameters.

* Required.

Returns

Array of `{ id, name, type, key_prefix, owner_id, created_at }`. Use the `id` in other tool calls.

Example request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_projects",
    "arguments": {}
  }
}

Try it (runs as you)

Executes the tool against your UpliftPM account with your permissions — same code path MCP clients use, without OAuth.

list_sprints
Read-only

List a project's sprints with names, status, dates and progress stats. Use it to resolve sprint ids to names.

Parameters

NameTypeDescription
projectId*uuidProject id.
status"planned" | "active" | "completed"Filter by status.

* Required.

Returns

Array of `{ id, name, goal, status, startDate, endDate, order, closedAt, stats }`.

Example request

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "list_sprints",
    "arguments": {
      "projectId": "3f1c…",
      "status": "active"
    }
  }
}

Try it (runs as you)

Executes the tool against your UpliftPM account with your permissions — same code path MCP clients use, without OAuth.

get_sprint
Read-only

Fetch one sprint with task counts per category and story points.

Parameters

NameTypeDescription
projectId*uuidProject id.
sprintId*uuidSprint id.

* Required.

Returns

`{ sprint: { id, name, goal, status, startDate, endDate, stats } }`.

Example request

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_sprint",
    "arguments": {
      "projectId": "3f1c…",
      "sprintId": "9a2b…"
    }
  }
}

Try it (runs as you)

Executes the tool against your UpliftPM account with your permissions — same code path MCP clients use, without OAuth.

list_tasks
Read-only

List tasks in a project. Optional filters narrow by sprint, epic, assignee, priority, or type. Returns up to 200 tasks.

Parameters

NameTypeDescription
projectId*uuidProject id from list_projects.
sprintIduuidOnly tasks in this sprint.
sprint"active" | "backlog"Active sprint or backlog shortcut.
category"todo" | "in_progress" | "done"Filter by column category.
epicIduuidOnly tasks in this epic.
assigneeIduuidOnly tasks assigned to this user.
priority"low" | "medium" | "high" | "urgent"Filter by priority.
type"story" | "task" | "bug"Filter by task type.

* Required.

Returns

Array of task summaries with `task_key`, `title`, `type`, `priority`, `story_points`, `is_blocked`, `assignee_id`, `sprint_id`, `epic_id`, `column_id`.

Example request

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "list_tasks",
    "arguments": {
      "projectId": "3f1c…",
      "priority": "high"
    }
  }
}

Try it (runs as you)

Executes the tool against your UpliftPM account with your permissions — same code path MCP clients use, without OAuth.

get_task
Read-only

Fetch full detail for one task by its human key (e.g. IT-42) within a project.

Parameters

NameTypeDescription
projectId*uuidProject id.
taskKey*stringHuman task key such as IT-42.

* Required.

Returns

Full task row with all columns.

Example request

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "get_task",
    "arguments": {
      "projectId": "3f1c…",
      "taskKey": "IT-42"
    }
  }
}

Try it (runs as you)

Executes the tool against your UpliftPM account with your permissions — same code path MCP clients use, without OAuth.

create_task
Mutates data

Create a new task in a project. Auto-allocates the task key (e.g. IT-43) and places the task in the first column. Requires editor+ access to the project.

Parameters

NameTypeDescription
projectId*uuidProject id.
title*string (1–300)Task title.
descriptionstring (≤40000)Rich text or markdown body.
type"story" | "task" | "bug"Defaults to "task".
priority"low" | "medium" | "high" | "urgent"Defaults to "medium".
storyPointsint 0–100Fibonacci points (0, 1, 2, 3, 5, 8, 13).
sprintIduuid | nullPlace in this sprint. Omit or null = backlog.
epicIduuid | nullLink to an epic.
assigneeIduuid | nullAssign to a project member.

* Required.

Returns

Created task row, including the newly allocated `task_key`.

Example request

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "create_task",
    "arguments": {
      "projectId": "3f1c…",
      "title": "Add dark-mode toggle",
      "type": "task",
      "priority": "high",
      "storyPoints": 3
    }
  }
}

Try it (runs as you)

Executes the tool against your UpliftPM account with your permissions — same code path MCP clients use, without OAuth.

update_task
Mutates data

Update fields on an existing task by human key. Only the provided fields change. Requires editor+ access.

Parameters

NameTypeDescription
projectId*uuidProject id.
taskKey*stringTask key such as IT-42.
titlestring (1–300)New title.
descriptionstring (≤40000)New body.
priority"low" | "medium" | "high" | "urgent"New priority.
storyPointsint 0–100New story points.
isBlockedbooleanMark blocked/unblocked.
assigneeIduuid | nullReassign, or null to unassign.
sprintIduuid | nullMove to sprint, or null for backlog.
epicIduuid | nullLink/unlink from an epic.
columnIduuidMove to a specific board column.

* Required.

Returns

Updated task row.

Example request

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "update_task",
    "arguments": {
      "projectId": "3f1c…",
      "taskKey": "IT-42",
      "priority": "urgent",
      "isBlocked": true
    }
  }
}

Try it (runs as you)

Executes the tool against your UpliftPM account with your permissions — same code path MCP clients use, without OAuth.

add_comment
Mutates data

Add a comment to a task, addressed by its human key.

Parameters

NameTypeDescription
projectId*uuidProject id.
taskKey*stringTask key such as IT-42.
body*string (1–10000)Comment text. Supports @mentions.

* Required.

Returns

Created comment row.

Example request

{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "tools/call",
  "params": {
    "name": "add_comment",
    "arguments": {
      "projectId": "3f1c…",
      "taskKey": "IT-42",
      "body": "Reproduced on staging — investigating."
    }
  }
}

Try it (runs as you)

Executes the tool against your UpliftPM account with your permissions — same code path MCP clients use, without OAuth.

list_epics
Read-only

List epics available in a project: epics owned by it plus shared epics explicitly linked to it. Optional status filter. Returns up to 200 epics ordered by newest first.

Parameters

NameTypeDescription
projectId*uuidProject id.
status"open" | "in_progress" | "done"Filter by status.

* Required.

Returns

Array of epics with `id, name, description, color, status, reporter_id, created_at, homeProjectId, isShared`.

Example request

{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {
    "name": "list_epics",
    "arguments": {
      "projectId": "3f1c…"
    }
  }
}

Try it (runs as you)

Executes the tool against your UpliftPM account with your permissions — same code path MCP clients use, without OAuth.

get_epic
Read-only

Fetch one epic, the projects it is linked to, its child tasks and a todo/in_progress/done progress summary.

Parameters

NameTypeDescription
epicId*uuidEpic id.

* Required.

Returns

`{ epic, projects: [{ id, name, isHome }], tasks[] (with project_id), progress: { todo, in_progress, done, total } }`.

Example request

{
  "jsonrpc": "2.0",
  "id": 11,
  "method": "tools/call",
  "params": {
    "name": "get_epic",
    "arguments": {
      "epicId": "9a2e…"
    }
  }
}

Try it (runs as you)

Executes the tool against your UpliftPM account with your permissions — same code path MCP clients use, without OAuth.

create_epic
Mutates data

Create an epic in a project. Epics belong to one project — an epic with the same name in another project is a separate epic. Requires editor+ access. Agents cannot create epics.

Parameters

NameTypeDescription
projectId*uuidProject id.
name*string (1–200)Epic name.
descriptionstring (≤40000)Rich text or markdown body.
colorhex string #rrggbbDefaults to #7c3aed.
status"open" | "in_progress" | "done"Defaults to "open".

* Required.

Returns

Created epic row.

Example request

{
  "jsonrpc": "2.0",
  "id": 12,
  "method": "tools/call",
  "params": {
    "name": "create_epic",
    "arguments": {
      "projectId": "3f1c…",
      "name": "Onboarding revamp",
      "color": "#7c3aed"
    }
  }
}

Try it (runs as you)

Executes the tool against your UpliftPM account with your permissions — same code path MCP clients use, without OAuth.

update_epic
Mutates data

Update fields on an epic. Only provided fields change. Agents cannot update epics.

Parameters

NameTypeDescription
epicId*uuidEpic id.
namestring (1–200)New name.
descriptionstring (≤40000)New body.
colorhex string #rrggbbNew color.
status"open" | "in_progress" | "done"New status.

* Required.

Returns

Updated epic row.

Example request

{
  "jsonrpc": "2.0",
  "id": 13,
  "method": "tools/call",
  "params": {
    "name": "update_epic",
    "arguments": {
      "epicId": "9a2e…",
      "status": "in_progress"
    }
  }
}

Try it (runs as you)

Executes the tool against your UpliftPM account with your permissions — same code path MCP clients use, without OAuth.

delete_epic
Mutates data

Delete an epic (and all its project links). Linked tasks remain; their epic_id is cleared. Agents cannot delete epics.

Parameters

NameTypeDescription
epicId*uuidEpic id.

* Required.

Returns

`{ ok: true, epicId }`.

Example request

{
  "jsonrpc": "2.0",
  "id": 16,
  "method": "tools/call",
  "params": {
    "name": "delete_epic",
    "arguments": {
      "epicId": "9a2e…"
    }
  }
}

Try it (runs as you)

Executes the tool against your UpliftPM account with your permissions — same code path MCP clients use, without OAuth.

Working on a task

How an agent takes a task, opens a pull request and ties the two together. Add this to the repository's agent instructions (for Claude Code, CLAUDE.md):

## Working on a task
1. Take a task with the UpliftPM MCP: get_task (taskKey like WEB-12, includeComments: true). Read the description and comments first.
2. Move it to the in-progress column: list_columns, then update_task with that column's id as columnId.
3. Create a branch named after the task: WEB-12-short-description.
4. Make the change. Commit messages start with the key: "WEB-12: what changed".
5. Open a pull request:
   - title: "WEB-12: what changed"
   - description: what and why, plus "Task: <taskUrl>" (taskUrl is in the get_task result)
6. Right after opening it, call link_pull_request (taskKey, the pull request's url, its title),
   then move the task to the review column if the project has one.
7. Never merge it, and never move a task to Done (the tools refuse): a person reviews, merges and closes it.

Optional, in the repository on GitHub: Settings → Autolink references. Prefix WEB-, URL https://<your app>/project/<project id>/task/WEB-<num>. Every WEB-12 written in a pull request's description, comments and commit messages becomes a link to the task. (Whether titles are linked too is not confirmed; that is why the description carries the full address.)

If the project has a GitHub repository connected (Project settings → Git), GitHub tells the app about every pull request, and one that has the task's key in its title, branch or description appears on the task by itself, with its state (open, draft, merged, closed). link_pull_request is then optional.

Without a connected repository, the pull request is linked by what the agent reports. Nothing is checked on GitHub's side, and the task does not change when the pull request is merged (with a connected repository the project can choose columns for “pull request opened” and “merged” in Project settings → Git, and the task is moved there; off by default). An agent can move a task between columns with update_task (columnId, e.g. To Do → In Progress → Review) but not into a Done column: a person marks it done.

Notes