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.
/mcpMCP Streamable HTTP (spec 2025-06-18).
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.
Content-Type: application/json
Accept: application/json, text/event-stream
Authorization: Bearer <access_token>Available tools
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 a project's sprints with names, status, dates and progress stats. Use it to resolve sprint ids to names.
Parameters
| Name | Type | Description |
|---|---|---|
| projectId* | uuid | Project 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.
Fetch one sprint with task counts per category and story points.
Parameters
| Name | Type | Description |
|---|---|---|
| projectId* | uuid | Project id. |
| sprintId* | uuid | Sprint 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 in a project. Optional filters narrow by sprint, epic, assignee, priority, or type. Returns up to 200 tasks.
Parameters
| Name | Type | Description |
|---|---|---|
| projectId* | uuid | Project id from list_projects. |
| sprintId | uuid | Only tasks in this sprint. |
| sprint | "active" | "backlog" | Active sprint or backlog shortcut. |
| category | "todo" | "in_progress" | "done" | Filter by column category. |
| epicId | uuid | Only tasks in this epic. |
| assigneeId | uuid | Only 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.
Fetch full detail for one task by its human key (e.g. IT-42) within a project.
Parameters
| Name | Type | Description |
|---|---|---|
| projectId* | uuid | Project id. |
| taskKey* | string | Human 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 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
| Name | Type | Description |
|---|---|---|
| projectId* | uuid | Project id. |
| title* | string (1–300) | Task title. |
| description | string (≤40000) | Rich text or markdown body. |
| type | "story" | "task" | "bug" | Defaults to "task". |
| priority | "low" | "medium" | "high" | "urgent" | Defaults to "medium". |
| storyPoints | int 0–100 | Fibonacci points (0, 1, 2, 3, 5, 8, 13). |
| sprintId | uuid | null | Place in this sprint. Omit or null = backlog. |
| epicId | uuid | null | Link to an epic. |
| assigneeId | uuid | null | Assign 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 fields on an existing task by human key. Only the provided fields change. Requires editor+ access.
Parameters
| Name | Type | Description |
|---|---|---|
| projectId* | uuid | Project id. |
| taskKey* | string | Task key such as IT-42. |
| title | string (1–300) | New title. |
| description | string (≤40000) | New body. |
| priority | "low" | "medium" | "high" | "urgent" | New priority. |
| storyPoints | int 0–100 | New story points. |
| isBlocked | boolean | Mark blocked/unblocked. |
| assigneeId | uuid | null | Reassign, or null to unassign. |
| sprintId | uuid | null | Move to sprint, or null for backlog. |
| epicId | uuid | null | Link/unlink from an epic. |
| columnId | uuid | Move 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 a comment to a task, addressed by its human key.
Parameters
| Name | Type | Description |
|---|---|---|
| projectId* | uuid | Project id. |
| taskKey* | string | Task 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.
Record a GitHub pull request on the task it implements: adds a comment `Pull request: <url>`. Call it once, right after opening the pull request; linking the same one again changes nothing. See “Working on a task” below for how to name the pull request.
Parameters
| Name | Type | Description |
|---|---|---|
| projectId* | uuid | Project id. |
| taskKey* | string | Task key such as WEB-12. |
| url* | string | https://github.com/<owner>/<repo>/pull/<number>. Only github.com pull request addresses are accepted. |
| title | string (≤200) | The pull request's title, shown under the link. |
* Required.
Returns
{ alreadyLinked, pullRequest, taskKey, taskUrl, commentId } — put taskUrl in the pull request's description.
Example request
{
"jsonrpc": "2.0",
"id": 9,
"method": "tools/call",
"params": {
"name": "link_pull_request",
"arguments": {
"projectId": "3f1c…",
"taskKey": "WEB-12",
"url": "https://github.com/acme/site/pull/7",
"title": "WEB-12: Fix login redirect"
}
}
}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 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
| Name | Type | Description |
|---|---|---|
| projectId* | uuid | Project 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.
Fetch one epic, the projects it is linked to, its child tasks and a todo/in_progress/done progress summary.
Parameters
| Name | Type | Description |
|---|---|---|
| epicId* | uuid | Epic 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 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
| Name | Type | Description |
|---|---|---|
| projectId* | uuid | Project id. |
| name* | string (1–200) | Epic name. |
| description | string (≤40000) | Rich text or markdown body. |
| color | hex string #rrggbb | Defaults 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 fields on an epic. Only provided fields change. Agents cannot update epics.
Parameters
| Name | Type | Description |
|---|---|---|
| epicId* | uuid | Epic id. |
| name | string (1–200) | New name. |
| description | string (≤40000) | New body. |
| color | hex string #rrggbb | New 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.
Deliberately share an epic with another project so several teams track work under one epic. Requires admin/owner access on the target project.
Parameters
| Name | Type | Description |
|---|---|---|
| epicId* | uuid | Epic id. |
| projectId* | uuid | Project to link. |
* Required.
Returns
`{ ok: true, epicId, projectId }`.
Example request
{
"jsonrpc": "2.0",
"id": 14,
"method": "tools/call",
"params": {
"name": "link_epic_to_project",
"arguments": {
"epicId": "9a2e…",
"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.
Remove a project from a shared epic. No tasks are deleted — that project's tasks simply lose their epic reference. Not allowed on the epic's home project (use delete_epic).
Parameters
| Name | Type | Description |
|---|---|---|
| epicId* | uuid | Epic id. |
| projectId* | uuid | Project to unlink. |
* Required.
Returns
`{ ok: true, epicId, projectId }`.
Example request
{
"jsonrpc": "2.0",
"id": 15,
"method": "tools/call",
"params": {
"name": "unlink_epic_from_project",
"arguments": {
"epicId": "9a2e…",
"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.
Delete an epic (and all its project links). Linked tasks remain; their epic_id is cleared. Agents cannot delete epics.
Parameters
| Name | Type | Description |
|---|---|---|
| epicId* | uuid | Epic 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
- All IDs are UUIDs except `taskKey`, which is the human key like `IT-42`.
- Write tools require at least editor role on the target project.
- Dedicated MCP bot? Create a separate account (e.g.
mcp-bot@your-domain), invite it to the project with role Agent (MCP). Agents can read/write tasks in the backlog only —sprintId/epicIdpassed by the agent are ignored. They can change a task's column (columnId), except into a Done column, and they cannot delete tasks or touch sprints/columns/epics. Connect the MCP in your assistant while signed in as that bot account. - Errors are returned as tool results with `isError: true` and a human-readable message.
- List endpoints cap at 200 rows; use filters to narrow.