---
title: "MCP Server for Claude & Other AI Clients | Orangescrum"
description: "Connect Claude or any Model Context Protocol client to Orangescrum: 72 tools across projects, tasks, sprints, time logs, and defects, secured with OAuth."
canonical: https://www.orangescrum.com/mcp
---

# MCP Server for Claude & Other AI Clients | Orangescrum

> For the complete documentation index, see [llms.txt](https://www.orangescrum.com/llms.txt).

Developer docs

Getting started

-   [Overview](/developer)
-   [Get API credentials](/developer#credentials)
-   [Make your first call](/developer#first-call)

Partner API

-   [Introduction](/developer/api)
-   [Authentication](/developer/api#authentication)
-   [Encrypting requests](/developer/api#encryption)
-   [Responses and errors](/developer/api#responses)
-   [Rate limits](/developer/api#rate-limits)
-   [Endpoint reference](/developer/api#reference)

MCP server

-   [Overview](/mcp)
-   [Connect a client](/mcp#connect)
-   [Tool reference](/mcp#tools)

More

-   [Self-Hosted edition](/self-hosted)
-   [Community Edition](/open-source/free-download)
-   [Talk to us](/contact-sales)

[Home](/)MCP server

# MCP server

Connect Claude, or any Model Context Protocol client, straight to your Orangescrum workspace. The assistant gets 72 tools and can answer questions about your real projects and create work for you, with your permissions and nothing more. There is no integration to build.

## What this is[](#what-is-mcp)

The Model Context Protocol is an open standard for connecting AI assistants to the systems where work actually lives. Instead of pasting project updates into a chat window, you point the assistant at Orangescrum once and it can read and act for itself.

Concretely, that means the assistant can:

-   Answer questions from live data: what is overdue, who is loaded, what shipped last sprint.
-   Create and update projects, tasks, subtasks, epics, features, and stories.
-   Run sprints: create one, start it, assign work to it, close it.
-   Log time, and read time logs back for reporting.
-   Drive test cases, scenarios, steps, and defects.
-   Manage checklists on any work item.

MCP or the REST API?

Use MCP when a person is working through an assistant and you want it to read and act without you writing code. Use the [Partner API](/developer/api) when your own software is doing the calling and you need scripted, predictable behaviour.

Just want the documentation?

This page documents the **product** MCP server: it runs on your own Orangescrum instance, needs OAuth, and reads your real projects and tasks. That is the one you want for day-to-day work.

There is also a small read-only **documentation** MCP server on this website at `https://www.orangescrum.com/mcp`, with no authentication and no workspace access. It exposes this site's public pages - search them, read any page as markdown, or list the site's machine-readable documents - which is useful when you want an assistant to answer questions about Orangescrum before connecting an account. Point a client at that URL, or `GET https://www.orangescrum.com/api` for every machine-readable endpoint this site publishes.

## Connect a client[](#connect)

The server speaks HTTP and authenticates with OAuth. Your client opens a browser window, you sign in to Orangescrum, and the connection is bound to your account. No API key to paste, no secret in a config file.

```
// claude_desktop_config.json
// macOS  ~/Library/Application Support/Claude/claude_desktop_config.json
// Windows  %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "orangescrum": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://<your-orangescrum-host>/mcp/partner"
      ]
    }
  }
}
```

Replace the host with your Orangescrum host. Restart the client after editing a config file.

Once connected, ask the client to list its tools. You should see the Orangescrum tools listed below. If nothing appears, the sign in probably did not complete: disconnect and add the server again.

## Try it[](#try-it)

Nothing special is needed to invoke a tool. Ask in plain language and the assistant picks the right one.

```
What is overdue across all my projects, and who owns each one?

Which tasks did I close yesterday? Draft my standup.

Show me the open defects on the Website Redesign project, worst first.
```

Give it standing context

The `add_project_context` tool stores notes that apply to every future conversation, such as your naming conventions, your definition of done, or who owns which area. It is the difference between an assistant that guesses and one that follows your process.

## Authentication[](#auth)

The primary endpoint is `/mcp/partner`, protected by OAuth bearer tokens. Clients discover how to authenticate automatically from these documents, so in most cases you only ever paste the server URL:

-   `/.well-known/oauth-authorization-server`
-   `/.well-known/oauth-protected-resource`
-   `/oauth/register`

Dynamic client registration is supported, which is why clients you have never configured before can connect with only a URL.

Permissions follow the person, not the assistant

Every tool call runs as the Orangescrum user who authorised the connection. An assistant cannot see a project that person cannot see, and cannot change anything they could not change. Connecting an assistant does not widen anyone's access, but it does mean whatever that person can do, the assistant can do on their behalf. Connect with the account whose scope you actually want to expose.

A legacy API key endpoint exists at `/mcp/partner-legacy` for integrations built before OAuth. It is disabled by default and kept only for migration. Use the OAuth endpoint for anything new.

## Tool reference[](#tools)

72 tools in 9 groups. You do not call these yourself, the assistant does, but knowing what exists tells you what you can reasonably ask for.

### Projects5[#](#mcp-projects)

Read, create, update, and search the projects in a workspace.

`list_projects`List every project the connected account can see, with optional status filter and paging.

| Name | Type | Required | Description |

| `page` | integer | No | Page number for pagination. |
| `limit` | integer | No | Number of items per page. |
| `status` | string | No | Filter by project status: active, inactive, or completed. |

`get_project`Get the full detail of one project.

| Name | Type | Required | Description |

| `project_id` | string | Yes | Project numeric id or uniq\_id. A task returns its project as project\_uniq\_id, which resolves here. |

`create_project`Create a project with a name, description, dates, and status.

| Name | Type | Required | Description |

| `name` | string | Yes | Project name. |
| `description` | string | No | Project description. |
| `start_date` | string | No | Start date in YYYY-MM-DD format. |
| `end_date` | string | No | End date in YYYY-MM-DD format. |
| `status` | string | No | Project status: Started, Hold, Stack, or Completed. |

`update_project`Update a project. Only the fields you send are changed.

| Name | Type | Required | Description |

| `project_id` | integer | Yes | Numeric id of the project to update. |
| `name` | string | No | New project name. |
| `description` | string | No | New project description. |
| `start_date` | string | No | Start date in YYYY-MM-DD format. |
| `end_date` | string | No | End date in YYYY-MM-DD format. |
| `status` | string | No | Project status: Started, Hold, Stack, or Completed. |

`search_projects`Search projects by free text with optional status, owner, and date filters.

| Name | Type | Required | Description |

| `q` | string | No | Free-text query matched against project name, short name, or description. |
| `status` | string | No | Filter by project status: active, inactive, or completed. |
| `status_group_id` | integer | No | Filter by status group id. |
| `owner_id` | integer | No | Filter by project owner user id. |
| `start_date` | string | No | Only projects starting on or after this date (YYYY-MM-DD). |
| `end_date` | string | No | Only projects ending on or before this date (YYYY-MM-DD). |
| `page` | integer | No | Page number. Default 1. |
| `limit` | integer | No | Items per page. Default 15, max 100. |

### Tasks and work items10[#](#mcp-tasks)

Work with tasks and the Scrum backlog hierarchy of Epic, Feature, Story, task, and subtask.

`list_tasks`List tasks, filtered by project, user, or status.

| Name | Type | Required | Description |

| `project_id` | integer | No | Filter tasks by project id. |
| `user_id` | integer | No | Filter tasks by user id. |
| `status` | string | No | Filter by status: pending, in\_progress, completed, or cancelled. |
| `page` | integer | No | Page number. Omit to return all matching tasks, up to 200. |
| `limit` | integer | No | Items per page, 1 to 100. Omit to return all matching tasks, up to 200. |

`list_tasks_v2`List tasks on the v2 contract, with strict project filtering, deterministic paging, and normalized ids.

| Name | Type | Required | Description |

| `project_id` | integer | No | Strict numeric project filter. |
| `mine` | boolean | No | When true, return only tasks assigned to the authenticated user. |
| `status` | string | No | Status filter as CSV or array values: open, in\_progress, pending, closed, completed, cancelled. |
| `page` | integer | No | Page number. Default 1. |
| `limit` | integer | No | Items per page. Default 20, max 100. |

`get_task`Get the full detail of one task.

| Name | Type | Required | Description |

| `task_id` | string | Yes | Task numeric id or uniq\_id. Both are returned by list\_tasks, search\_tasks, and get\_task. |

`create_task`Create a task in a project.

| Name | Type | Required | Description |

| `project_id` | string | Yes | Project numeric id or uniq\_id. |
| `title` | string | Yes | Task title. |
| `description` | string | No | Task description. |
| `assigned_to` | integer | No | User id to assign the task to. |
| `priority` | string | No | Priority: low, medium, high, or urgent. |
| `due_date` | string | No | Due date in YYYY-MM-DD format. |

`update_task`Update a task. Only the fields you send are changed.

| Name | Type | Required | Description |

| `task_id` | string | Yes | Task numeric id or uniq\_id. |
| `title` | string | No | New task title. |
| `description` | string | No | New task description. |
| `status` | string | No | Status: pending, in\_progress, completed, or cancelled. |
| `priority` | string | No | Priority: low, medium, high, or urgent. |
| `assigned_to` | integer | No | User id to assign the task to. |
| `due_date` | string | No | Due date in YYYY-MM-DD format. |

`search_tasks`Search tasks by free text with optional project, status, priority, and assignee filters.

| Name | Type | Required | Description |

| `q` | string | No | Free-text query matched against task title and description. |
| `project_id` | integer | No | Filter tasks by project id. |
| `status` | string | No | Filter by status: pending, in\_progress, completed, or cancelled. |
| `priority` | string | No | Filter by priority: low, medium, high, or urgent. |
| `assigned_to` | integer | No | Filter by assignee user id. |
| `page` | integer | No | Page number. Omit to return all matching tasks, up to 200. |
| `limit` | integer | No | Items per page, 1 to 100. Omit to return all matching tasks, up to 200. |

`create_epic`Create an Epic, the top level of the Scrum backlog, in a project. Orangescrum v4 projects only.

| Name | Type | Required | Description |

| `project_id` | string | Yes | Project numeric id or uniq\_id. |
| `title` | string | Yes | Epic title. |
| `description` | string | No | Epic description. |
| `assigned_to` | integer | No | User id to assign the epic to. |
| `priority` | string | No | Priority: low, medium, or high. |
| `due_date` | string | No | Due date in YYYY-MM-DD format. |
| `story_point` | integer | No | Story points. |

`create_feature`Create a Feature under an existing Epic. It inherits the project of that Epic. Orangescrum v4 projects only.

| Name | Type | Required | Description |

| `epic_id` | integer | Yes | Numeric id of the parent Epic. |
| `title` | string | Yes | Feature title. |
| `description` | string | No | Feature description. |
| `assigned_to` | integer | No | User id to assign the feature to. |
| `priority` | string | No | Priority: low, medium, or high. |
| `due_date` | string | No | Due date in YYYY-MM-DD format. |
| `story_point` | integer | No | Story points. |

`create_story`Create a Story, optionally under a Feature or an Epic. Orangescrum v4 projects only.

| Name | Type | Required | Description |

| `project_id` | string | Yes | Project numeric id or uniq\_id. |
| `title` | string | Yes | Story title. |
| `feature_id` | integer | No | Parent Feature id. The Story inherits the Epic of that Feature. |
| `epic_id` | integer | No | Parent Epic id. Ignored when feature\_id is given. |
| `description` | string | No | Story description. |
| `assigned_to` | integer | No | User id to assign the story to. |
| `priority` | string | No | Priority: low, medium, or high. |
| `due_date` | string | No | Due date in YYYY-MM-DD format. |
| `story_point` | integer | No | Story points. |

`create_subtask`Create a child item under a Story or a Task. The child inherits the project, Epic, and Feature of its parent. Orangescrum v4 projects only.

| Name | Type | Required | Description |

| `parent_task_id` | string | Yes | Parent Story or Task numeric id or uniq\_id. |
| `title` | string | Yes | Title of the child item. |
| `type_id` | integer | No | Type id. Defaults to the type of the parent. |
| `description` | string | No | Description. |
| `assigned_to` | integer | No | User id to assign the item to. |
| `priority` | string | No | Priority: low, medium, or high. |
| `due_date` | string | No | Due date in YYYY-MM-DD format. |
| `story_point` | integer | No | Story points. |

### Sprints7[#](#mcp-sprints)

Plan, run, and close sprints, and move tasks in and out of them. Orangescrum v4 projects only.

`list_sprints`List the active sprints of a project, with the running sprint first.

| Name | Type | Required | Description |

| `project_id` | string | Yes | Project numeric id or uniq\_id. |

`get_sprint`Get one sprint by its numeric id or uniq\_id.

| Name | Type | Required | Description |

| `sprint_id` | string | Yes | Sprint numeric id or uniq\_id. |

`create_sprint`Create a sprint in a project. It starts in the not-yet-started state.

| Name | Type | Required | Description |

| `project_id` | string | Yes | Project numeric id or uniq\_id. |
| `title` | string | Yes | Sprint title, unique within the project. |
| `description` | string | No | Sprint goal or description. |
| `start_date` | string | No | Planned start date in YYYY-MM-DD format. |
| `end_date` | string | No | Planned end date in YYYY-MM-DD format. |

`update_sprint`Update a sprint title, goal, or planned dates. Only the fields you send are changed.

| Name | Type | Required | Description |

| `sprint_id` | string | Yes | Sprint numeric id or uniq\_id. |
| `title` | string | No | New sprint title, unique within the project. |
| `description` | string | No | New sprint goal or description. |
| `start_date` | string | No | Planned start date in YYYY-MM-DD format. An empty string clears it. |
| `end_date` | string | No | Planned end date in YYYY-MM-DD format. An empty string clears it. |

`start_sprint`Start a sprint. Unless parallel sprints are enabled, only one sprint per project can run at a time.

| Name | Type | Required | Description |

| `sprint_id` | string | Yes | Sprint numeric id or uniq\_id. |
| `start_date` | string | No | Start date in YYYY-MM-DD format. Must be sent with end\_date. |
| `end_date` | string | No | End date in YYYY-MM-DD format. Must be sent with start\_date. |
| `title` | string | No | Rename the sprint as it starts. |
| `description` | string | No | Set the sprint goal as it starts. |

`complete_sprint`Close a sprint, snapshot the done tasks for velocity, and move the incomplete ones out.

| Name | Type | Required | Description |

| `sprint_id` | string | Yes | Sprint numeric id or uniq\_id. |
| `incomplete_destination` | string | No | Where incomplete tasks go: "backlog" (default) or "next\_sprint:<id>" for another active sprint in the same project. |

`assign_task_to_sprint`Move a top-level task into a sprint, or back to the backlog. Its descendants move with it.

| Name | Type | Required | Description |

| `task_id` | string | Yes | Task numeric id or uniq\_id. Must be a top-level task, not a subtask. |
| `sprint_id` | string | No | Target sprint numeric id or uniq\_id. Omit or leave empty to move the task to the backlog. |
| `position` | integer | No | Zero-based order of the task within the sprint. |

### Time logs3[#](#mcp-timelogs)

Read and record time logged against tasks.

`list_timelogs`List the time logs of the connected user, with optional project, task, and date filters.

| Name | Type | Required | Description |

| `project_id` | integer | No | Filter time logs by project id. |
| `task_id` | integer | No | Filter time logs by task id. |
| `from` | string | No | Start date (YYYY-MM-DD), inclusive. |
| `to` | string | No | End date (YYYY-MM-DD), inclusive. |
| `page` | integer | No | Page number. Default 1. |
| `limit` | integer | No | Items per page. Default 20, max 100. |

`create_timelog`Log time against a task. Send total\_hours, or send explicit start and end times.

| Name | Type | Required | Description |

| `project_id` | integer | Yes | Project id the time is logged against. |
| `task_id` | integer | No | Task id the time is logged against. |
| `task_date` | string | Yes | Date of the work in YYYY-MM-DD format. |
| `description` | string | Yes | Description of the work done. |
| `total_hours` | number | No | Total hours spent, as a decimal. For example 2.5 for two and a half hours. |
| `start_time` | string | No | Start time in HH:MM:SS format. Overrides the times derived from total\_hours. |
| `end_time` | string | No | End time in HH:MM:SS format. Overrides the times derived from total\_hours. |
| `is_billable` | boolean | No | Whether the time is billable. Default false. |

`update_timelog`Update a time log entry. Only the fields you send are changed.

| Name | Type | Required | Description |

| `timelog_id` | integer | Yes | Numeric id of the time log to update. |
| `task_date` | string | No | Date of the work in YYYY-MM-DD format. |
| `description` | string | No | Description of the work done. |
| `total_hours` | number | No | Total hours spent, as a decimal. |
| `start_time` | string | No | Start time in HH:MM:SS format. |
| `end_time` | string | No | End time in HH:MM:SS format. |
| `is_billable` | boolean | No | Whether the time is billable. |

### Users3[#](#mcp-users)

Look up the connected user and the other people in the company.

`get_current_user`Return the authenticated user profile, including timezone, roles, and default workspace.

This tool takes no arguments.

`list_users`List the users in the company, with an optional name or email search.

| Name | Type | Required | Description |

| `search` | string | No | Case-insensitive match on user name or email. |
| `page` | integer | No | Page number. Default 1. |
| `limit` | integer | No | Items per page. Default 20, max 100. |

`get_user`Get the detail of one user.

| Name | Type | Required | Description |

| `user_id` | string | Yes | User numeric id or uniq\_id. Both are returned by list\_users and get\_user. |

### Test management15[#](#mcp-test-management)

Manage test scenarios, test cases, and the steps inside a case. Orangescrum v4 workspaces only.

`list_test_scenarios`List test scenarios, with optional project, type, and status filters.

| Name | Type | Required | Description |

| `project_id` | string | No | Filter by project numeric id or uniq\_id. |
| `type` | string | No | Filter by scenario type. |
| `status` | string | No | Filter by status. |
| `q` | string | No | Search term matched against name and description. |
| `include_archived` | boolean | No | Include archived scenarios. |
| `page` | integer | No | Page number. Default 1. |
| `limit` | integer | No | Items per page. Default 20, max 100. |

`get_test_scenario`Get one test scenario by its uniq\_id.

| Name | Type | Required | Description |

| `scenario_id` | string | Yes | Test scenario uniq\_id. |

`create_test_scenario`Create a test scenario in a project.

| Name | Type | Required | Description |

| `project_id` | string | Yes | Project numeric id or uniq\_id. |
| `name` | string | Yes | Scenario name. |
| `description` | string | No | Scenario description. |
| `type` | string | No | Scenario type. |
| `coverage_percentage` | number | No | Coverage percentage, 0 to 100. |
| `status` | string | No | Status. Default Active. |

`update_test_scenario`Update a test scenario. Only the fields you send are changed.

| Name | Type | Required | Description |

| `scenario_id` | string | Yes | Test scenario uniq\_id. |
| `name` | string | No | Scenario name. |
| `description` | string | No | Scenario description. |
| `type` | string | No | Scenario type. |
| `coverage_percentage` | number | No | Coverage percentage, 0 to 100. |
| `status` | string | No | Status. |

`delete_test_scenario`Archive a test scenario, or delete it permanently.

| Name | Type | Required | Description |

| `scenario_id` | string | Yes | Test scenario uniq\_id. |
| `hard_delete` | boolean | No | Permanently delete instead of archive. |

`list_test_cases`List test cases, with optional project, scenario, status, and priority filters. Archived cases are excluded by default.

| Name | Type | Required | Description |

| `project_id` | string | No | Filter by project numeric id or uniq\_id. |
| `scenario_id` | string | No | Filter by parent test scenario uniq\_id. |
| `status` | string | No | Filter by status. |
| `priority` | string | No | Filter by priority. |
| `q` | string | No | Search term matched against name and description. |
| `include_archived` | boolean | No | Include archived test cases. |
| `page` | integer | No | Page number. Default 1. |
| `limit` | integer | No | Items per page. Default 20, max 100. |

`get_test_case`Get one test case by its uniq\_id.

| Name | Type | Required | Description |

| `test_case_id` | string | Yes | Test case uniq\_id. |

`create_test_case`Create a test case in a project, optionally attached to a test scenario.

| Name | Type | Required | Description |

| `project_id` | string | Yes | Project numeric id or uniq\_id. |
| `name` | string | Yes | Test case name. |
| `description` | string | No | Test case description. |
| `type` | string | No | Test case type. |
| `priority` | string | No | Priority, for example High, Medium, or Low. |
| `severity` | string | No | Severity. |
| `behaviour` | string | No | Behaviour, for example Positive or Negative. |
| `status` | string | No | Status. Default Active. |
| `scenario_id` | string | No | Parent test scenario uniq\_id. |
| `pre_condition` | string | No | Pre-condition. |
| `post_condition` | string | No | Post-condition. |
| `expected_result` | string | No | Expected result. |

`update_test_case`Update a test case. Only the fields you send are changed.

| Name | Type | Required | Description |

| `test_case_id` | string | Yes | Test case uniq\_id. |
| `name` | string | No | Test case name. |
| `description` | string | No | Test case description. |
| `type` | string | No | Test case type. |
| `priority` | string | No | Priority. |
| `severity` | string | No | Severity. |
| `behaviour` | string | No | Behaviour. |
| `status` | string | No | Status. |
| `scenario_id` | string | No | Parent test scenario uniq\_id. |
| `expected_result` | string | No | Expected result. |

`delete_test_case`Archive a test case, or delete it permanently along with its step links.

| Name | Type | Required | Description |

| `test_case_id` | string | Yes | Test case uniq\_id. |
| `hard_delete` | boolean | No | Permanently delete instead of archive. |

`list_test_steps`List the steps of a test case, in their ordered sequence.

| Name | Type | Required | Description |

| `test_case_id` | string | Yes | Parent test case uniq\_id. |
| `include_archived` | boolean | No | Include archived or unlinked steps. |
| `page` | integer | No | Page number. Default 1. |
| `limit` | integer | No | Items per page. Default 100, max 100. |

`create_test_step`Add a step to a test case. The step is appended to the end of the current order.

| Name | Type | Required | Description |

| `test_case_id` | string | Yes | Parent test case uniq\_id. |
| `name` | string | No | Step name or short label. |
| `description` | string | No | Step description. Required when no name is given. |
| `expected_result` | string | No | Expected result. |
| `outcome` | string | No | Actual outcome. |
| `status` | string | No | Status. Default Active. |

`update_test_step`Update one step of a test case. Only the fields you send are changed.

| Name | Type | Required | Description |

| `test_case_id` | string | Yes | Parent test case uniq\_id. |
| `step_id` | string | Yes | Test step uniq\_id. |
| `name` | string | No | Step name. |
| `description` | string | No | Step description. |
| `expected_result` | string | No | Expected result. |
| `outcome` | string | No | Actual outcome. |
| `status` | string | No | Status. |

`reorder_test_steps`Reorder the steps of a test case. Steps you leave out keep their relative order after the listed ones.

| Name | Type | Required | Description |

| `test_case_id` | string | Yes | Parent test case uniq\_id. |
| `step_ids` | array | Yes | Ordered list of test step uniq\_ids. |

`delete_test_step`Remove a step from a test case. The step is archived by default, or deleted permanently.

| Name | Type | Required | Description |

| `test_case_id` | string | Yes | Parent test case uniq\_id. |
| `step_id` | string | Yes | Test step uniq\_id. |
| `hard_delete` | boolean | No | Permanently delete instead of archive. |

### Defects6[#](#mcp-defects)

File defects, track their status, and link them to test cases, test steps, and tasks.

`list_defects`List defects, with optional project, status, priority, severity, test case, and text filters.

| Name | Type | Required | Description |

| `project_id` | string | No | Filter by project numeric id or uniq\_id. |
| `status` | string | No | Filter by status. |
| `priority` | string | No | Filter by priority. |
| `severity` | string | No | Filter by severity. |
| `test_case_id` | string | No | Filter by linked test case uniq\_id. |
| `q` | string | No | Search term matched against title, description, and defect number. |
| `page` | integer | No | Page number. Default 1. |
| `limit` | integer | No | Items per page. Default 20, max 100. |

`get_defect`Get one defect by its uniq\_id.

| Name | Type | Required | Description |

| `defect_id` | string | Yes | Defect uniq\_id. |

`create_defect`File a defect in a project. The defect number is generated for you and the status defaults to Open.

| Name | Type | Required | Description |

| `project_id` | string | Yes | Project numeric id or uniq\_id. |
| `title` | string | Yes | Defect title. |
| `description` | string | No | Defect description. |
| `type` | string | No | Defect type. |
| `priority` | string | No | Priority. |
| `severity` | string | No | Severity. |
| `status` | string | No | Status. Default Open. |
| `test_case_id` | string | No | Linked test case uniq\_id. |
| `test_step_id` | string | No | Linked test step uniq\_id. |
| `task_id` | string | No | Linked task uniq\_id. |

`update_defect`Update the descriptive fields of a defect. Use set\_defect\_status and link\_defect for status and links.

| Name | Type | Required | Description |

| `defect_id` | string | Yes | Defect uniq\_id. |
| `title` | string | No | Defect title. |
| `description` | string | No | Defect description. |
| `type` | string | No | Defect type. |
| `priority` | string | No | Priority. |
| `severity` | string | No | Severity. |

`link_defect`Link a defect to a test case, a test step, or a task. Give at least one target.

| Name | Type | Required | Description |

| `defect_id` | string | Yes | Defect uniq\_id. |
| `test_case_id` | string | No | Test case uniq\_id to link. |
| `test_step_id` | string | No | Test step uniq\_id to link. |
| `task_id` | string | No | Task uniq\_id to link. |

`set_defect_status`Change the status of a defect. Resolved and closed states also record who resolved it and when.

| Name | Type | Required | Description |

| `defect_id` | string | Yes | Defect uniq\_id. |
| `status` | string | Yes | New status, for example Open, In Progress, Resolved, or Closed. |

### Checklists20[#](#mcp-checklists)

Manage the company checklist catalogue and templates, and the checklists attached to individual work items.

`get_checklist_config`Read the company checklist configuration: whether it is on, the policy flags, and the required-groups matrix.

| Name | Type | Required | Description |

| `work_item_type` | string | No | Filter the required-groups matrix. One of: epic, feature, story, task, defect, test\_scenario, test\_case, test\_defect, project, program. |

`list_checklist_groups`List the company catalogue checklist groups, both system and custom.

| Name | Type | Required | Description |

| `active_only` | boolean | No | When true, return only active groups. |

`create_checklist_group`Create a custom checklist group in the company catalogue. Names must be unique per company.

| Name | Type | Required | Description |

| `name` | string | Yes | Group name, unique per company. |
| `color` | string | No | Hex colour, for example #3366ff. |
| `is_active` | boolean | No | Whether the group is active. Default true. |

`update_checklist_group`Update a catalogue checklist group. System groups cannot be renamed, only recoloured or deactivated.

| Name | Type | Required | Description |

| `group_id` | integer | Yes | Catalogue group id. |
| `name` | string | No | New name. Custom groups only. |
| `color` | string | No | New hex colour, for example #3366ff. |
| `is_active` | boolean | No | Whether the group is active. |

`delete_checklist_group`Delete a custom catalogue checklist group and its templates. System groups cannot be deleted.

| Name | Type | Required | Description |

| `group_id` | integer | Yes | Catalogue group id. |

`list_checklist_templates`List the company checklist templates with their items.

This tool takes no arguments.

`create_checklist_template`Create a checklist template that owns one catalogue group and a list of item labels.

| Name | Type | Required | Description |

| `checklist_group_id` | integer | Yes | Catalogue group this template owns. |
| `name` | string | Yes | Template name. |
| `auto_attach` | boolean | No | Auto-apply to new work items of the enabled types. Default false. |
| `is_active` | boolean | No | Whether the template is active. Default true. |
| `items` | array | No | Ordered checklist item labels. |

`update_checklist_template`Update a checklist template. Sending items replaces the whole item list.

| Name | Type | Required | Description |

| `template_id` | integer | Yes | Template id. |
| `name` | string | No | New template name. |
| `checklist_group_id` | integer | No | Move the template to a different catalogue group. |
| `auto_attach` | boolean | No | Whether to auto-apply on create. |
| `is_active` | boolean | No | Whether the template is active. |
| `items` | array | No | Replacement ordered item labels. Omit to leave items unchanged. |

`delete_checklist_template`Delete a checklist template and its items.

| Name | Type | Required | Description |

| `template_id` | integer | Yes | Template id. |

`get_work_item_checklist`Read the checklist of a work item: its groups, the nested items, and the completion status.

| Name | Type | Required | Description |

| `work_item_type` | string | Yes | One of: epic, feature, story, task, defect, test\_scenario, test\_case, test\_defect, project, program. |
| `work_item_id` | integer | Yes | Numeric id of the work item. |

`add_checklist_item`Add an item to a checklist group on a work item. Returns the refreshed checklist.

| Name | Type | Required | Description |

| `work_item_type` | string | Yes | One of: epic, feature, story, task, defect, test\_scenario, test\_case, test\_defect, project, program. |
| `work_item_id` | integer | Yes | Numeric id of the work item. |
| `work_item_group_id` | integer | Yes | Work-item group instance to add the item to. Read it from get\_work\_item\_checklist. |
| `label` | string | Yes | Checklist item text. |

`update_checklist_item`Change the text of a checklist item. Returns the refreshed checklist.

| Name | Type | Required | Description |

| `item_id` | integer | Yes | Checklist item id. |
| `label` | string | Yes | New item text. |

`complete_checklist_item`Mark a checklist item complete or incomplete, and stamp the acting user as the completer.

| Name | Type | Required | Description |

| `item_id` | integer | Yes | Checklist item id. |
| `is_completed` | boolean | No | True to complete, false to uncomplete. Omit to toggle. |

`delete_checklist_item`Delete a checklist item from a work item. Returns the refreshed checklist.

| Name | Type | Required | Description |

| `item_id` | integer | Yes | Checklist item id. |

`add_checklist_group`Attach an existing catalogue checklist group to a work item. Duplicate attaches are rejected.

| Name | Type | Required | Description |

| `work_item_type` | string | Yes | One of: epic, feature, story, task, defect, test\_scenario, test\_case, test\_defect, project, program. |
| `work_item_id` | integer | Yes | Numeric id of the work item. |
| `source_group_id` | integer | Yes | Catalogue group id to attach. |

`add_checklist_group_from_template`Copy a checklist template, group and items, onto a work item as an independent group.

| Name | Type | Required | Description |

| `work_item_type` | string | Yes | One of: epic, feature, story, task, defect, test\_scenario, test\_case, test\_defect, project, program. |
| `work_item_id` | integer | Yes | Numeric id of the work item. |
| `template_id` | integer | Yes | Checklist template id to copy. |

`create_custom_checklist_group`Create a one-off checklist group directly on a work item. Allowed only when the company enables custom groups.

| Name | Type | Required | Description |

| `work_item_type` | string | Yes | One of: epic, feature, story, task, defect, test\_scenario, test\_case, test\_defect, project, program. |
| `work_item_id` | integer | Yes | Numeric id of the work item. |
| `name` | string | Yes | Custom group name. |

`rename_checklist_group`Rename a checklist group on one work item. The shared catalogue is never touched.

| Name | Type | Required | Description |

| `work_item_group_id` | integer | Yes | Work-item group instance id. |
| `name` | string | Yes | New group name. |

`reorder_checklist_groups`Set the display order of the checklist groups on a work item.

| Name | Type | Required | Description |

| `work_item_type` | string | Yes | One of: epic, feature, story, task, defect, test\_scenario, test\_case, test\_defect, project, program. |
| `work_item_id` | integer | Yes | Numeric id of the work item. |
| `group_ids` | array | Yes | Work-item group instance ids in the desired order. |

`delete_work_item_checklist_group`Remove a checklist group and its items from one work item. The catalogue group is left alone.

| Name | Type | Required | Description |

| `work_item_group_id` | integer | Yes | Work-item group instance id. |

### Search and context3[#](#mcp-search-context)

Search the workspace documents and read or save the standing context an assistant should remember.

`search_documents`Search the documents uploaded to the workspace by meaning and return the most relevant excerpts with their source. Orangescrum v4 workspaces only.

| Name | Type | Required | Description |

| `query` | string | Yes | What to look for, in natural language. |
| `project_id` | integer | No | Project id to scope the search to one project. |
| `limit` | integer | No | Maximum excerpts to return, 1 to 20. Default 5. |

`get_project_context`Read the standing context saved for this workspace: background, conventions, and instructions. Orangescrum v4 projects only.

| Name | Type | Required | Description |

| `project_id` | string | No | Project numeric id or uniq\_id. Omit to get company-wide entries only. |

`add_project_context`Save a standing context entry so it is recalled in later conversations. This is a write action and asks the user to confirm. Orangescrum v4 projects only.

| Name | Type | Required | Description |

| `title` | string | Yes | Short label for the entry. |
| `body` | string | Yes | The fact, convention, or instruction to remember. |
| `project_id` | string | No | Project numeric id or uniq\_id to scope the entry. Omit for a company-wide entry. |

## Resources and prompts[](#resources)

Alongside tools, the server exposes read-only **resources** that a client can pull in as context, and **prompts** that package a common request.

### Resources

| Name | URI | What it returns |

| `projects` | orangescrum://projects | All projects in the authenticated workspace, with status and progress. Returned as Markdown. |
| `my-tasks` | orangescrum://my-tasks | Open tasks assigned to the authenticated user across all projects. Returned as Markdown. |
| `context` | orangescrum://context | Company-wide standing context that applies to every project in the workspace. Returned as Markdown. |

### Prompts

| Name | What it does |

| `daily_standup` | Draft a daily standup message from the tasks you closed yesterday and the ones open today. |
| `overdue_report` | Summarize your overdue tasks by project and suggest what to prioritize or escalate. |

## Availability[](#availability)

The MCP server is available in the **Cloud edition**. Self-hosted support is planned but not shipped, so if you run Orangescrum on your own servers today, use the [Partner API](/developer/api), which is available in both Cloud and Self-Hosted.

API and MCP access sit on the Premium plan. [Compare plans](/pricing), or [talk to us](/contact-sales) if you want to work through what you are building first.