# Tools

> What the MCP server exposes to your assistant — coverage across projects, tasks, timelogs and users.

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

Source: https://helpdesk.orangescrum.com/guide/mcp/tools

---
The server advertises **15 tools**: create, read, update and search operations
across four domains.

> **Ask the server, not this page**
>
> Tool names are part of the server's contract and can change between
> deployments. The authoritative list for the endpoint you are pointed at always
> comes from `tools/list`:
> ```bash
> curl -sS -X POST https://v4-api.orangescrum.com/mcp/partner \
> -H 'Content-Type: application/json' \
> -H 'X-API-KEY: YOUR_KEY' \
> -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
> ```
> You can also just ask your assistant: *"what Orangescrum tools do you have?"*

## Coverage

| Domain | Read | Write | Search |
| --- | :---: | :---: | :---: |
| Projects | ✓ | ✓ | ✓ |
| Tasks | ✓ | ✓ | ✓ |
| Timelogs | ✓ | ✓ | ✓ |
| Users | ✓ | — | — |

### Projects

List projects, fetch a single project's detail, create a project, update one,
and search across them. Projects are addressed by UUID.

### Tasks

The same shape as projects — list, detail, create, update, search. Tasks carry
title, description, assignee, priority, status, estimate, start date and due
date.

### Timelogs

List, detail, create, update and search time entries. This is what makes
"log two hours against OS-431 for yesterday" work.

### Users

Read-only: list the workspace directory and fetch a single user. Your assistant
needs this to resolve a name like "Priya" into the numeric id that assignment
fields expect.

> **Users are read-only over MCP**
>
> There is no tool to invite, deactivate or change a user. Those stay in the
> admin UI deliberately — an assistant should not be able to alter who has
> access to your workspace.

## Scopes decide what actually works

The tool list your assistant sees is the server's full catalogue; whether a call
*succeeds* depends on your key's scopes. A read-only key still shows write tools,
but calling one returns `403`.

This is the main safety control:

- **Read-only key**: The assistant can answer questions about your workspace and nothing else. Start here.

- **Read-write key**: The assistant can create and change real records. Use once you trust the workflows.

## What these tools are good at

- **Cross-project questions**: "What's overdue across everything I own?" — tedious by hand, one call for an assistant.

- **Bulk tidying**: "Find sprint tasks with no estimate and list them" — search plus a filter.

- **Capture from context**: Turn a chat thread or a code review into tasks without leaving the editor.

- **Time reconstruction**: "Log yesterday's work from my commits" — reads git, writes timelogs.

## Limits worth knowing

- **No bulk endpoints.** Creating twenty tasks is twenty calls, and each counts
  against the [rate limit](https://helpdesk.orangescrum.com/guide/api/rate-limits).
- **No idempotency key.** A retried create makes a second record. If a write
  appears to fail, have the assistant search before retrying.
- **Not everything in the REST API is a tool.** The MCP surface covers the four
  domains above; test cases, defects and checklists are
  [REST endpoints](https://helpdesk.orangescrum.com/guide/api/introduction) only.

- [Prompts](https://helpdesk.orangescrum.com/guide/mcp/prompts): Two ready-made workflows exposed as slash commands.