---
metadata:
  - name: generator
    content: Diplodoc Platform v5.61.1
  - property: og:type
    content: article
  - property: article:section
    content: Integration with other services
  - property: og:title
    content: Tracker MCP server
  - property: article:tag
    content: Technical instruction
alternate:
  - https://yandex.com.tr/support/tracker/en/user/mcp-server.md
  - href: https://yandex.com.tr/support/tracker/en/user/mcp-server.md
    type: text/markdown
    title: Markdown version
  - href: https://yandex.com.tr/support/tracker/en/llms.txt
    rel: describedby
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.com.tr/support/tracker/en/llms.txt


# Tracker MCP server

MCP (Model Context Protocol) is a standard protocol for connecting external tools to AI assistants. Connect the Tracker MCP server to give an assistant access to your organization's issues, projects, and goals.

The server runs requests on behalf of the token owner and with their permissions. It does not have its own account and passes your credentials to Yandex Tracker API unchanged.

## MCP server capabilities {#capabilities}

Using the MCP server, an assistant can:

- work with issues: search, read, create, update fields, change status, and view change history;
- read, add, update, and delete comments;
- work with time tracking: read, create, update, and delete worklogs;
- work with boards and sprints: view them, create sprints, and move sprints;
- search, read, create, and update projects, portfolios, and goals, including their links, comments, checklists, and key results;
- get reference data: queues, priorities, issue types, resolutions, available transitions, queue forms, and users;
- view attachments, get their metadata and a temporary download link, and upload files;
- configure queue triggers;
- bulk-update fields, change issue status, and move issues between queues.

The MCP server provides 72 tools. It does not provide arbitrary API access: every tool performs a named operation with validated parameters.

## Connect the server {#connection}

To connect the Tracker MCP server to an AI assistant:

1. Get an OAuth token or IAM token to access the API. For details, see [API access](https://yandex.com.tr/support/tracker/en/api/access.md). Use an IAM token for a Yandex Cloud organization; it is valid for up to 12 hours.
1. Open [**Administration → Organizations**](https://tracker.yandex.com/admin/orgs) and copy the value of the **ID** field.
1. Add the MCP server configuration to your AI assistant settings. Specify the URL and headers from the table below.
1. Verify the connection. For example, in Codex, run `/mcp`: the server and its tools should appear in the list.

Connection parameters:

| **Parameter** | **Value** |
| --- | --- |
| URL | `https://mcp.tracker.yandex.net/mcp`<br>For an internal installation or test environment: `https://<host>/api/mcp` |
| Transport | Streamable HTTP, `POST` method. Sessions are not used. |
| `Authorization` header | `OAuth <token>` or `Bearer <IAM_token>`. The server passes the header to the API unchanged. |
| Organization ID | `X-Collab-Org-ID` header with the organization ID value. `X-Cloud-Org-Id`, `X-Org-Id`, `X-Tracker-Org-Id`, and `X-Tracker-Id` are also supported. |
| `Accept` header | `application/json, text/event-stream`. Required. |

## Connection examples {#connection-examples}

How you add an MCP configuration depends on the AI tool. Usually, you only need to specify the server URL and required headers.

### Codex configuration {#codex}

For an internal Tracker installation, use the `OAuth` scheme. The `--bearer-token-env-var` option is not suitable because it sends the value using the `Bearer` scheme. Specify the full `Authorization` header instead.

Add the following configuration to `~/.codex/config.toml`:

```toml
[mcp_servers.tracker]
url = "https://mcp.tracker.yandex.net/mcp"
env_http_headers = { Authorization = "TRACKER_MCP_AUTHORIZATION", "X-Collab-Org-ID" = "TRACKER_MCP_ORG_ID" }
default_tools_approval_mode = "writes"
```

Before starting Codex, set the environment variables:

```bash
export TRACKER_MCP_AUTHORIZATION="OAuth <token>"
export TRACKER_MCP_ORG_ID="<organization_id>"
codex
```

### Claude Code configuration {#claude-code}

Single quotes preserve the environment variable reference in `.mcp.json` instead of replacing it with the token value:

```bash
export TRACKER_OAUTH_TOKEN="<token>"

claude mcp add \
  --transport http \
  --scope project \
  --header 'Authorization: OAuth ${TRACKER_OAUTH_TOKEN}' \
  --header 'X-Collab-Org-ID: <organization_id>' \
  tracker \
  https://mcp.tracker.yandex.net/mcp
```

### Other MCP client configuration {#other-client}

Specify the `http` server type, URL, and required headers. For example:

```json
{
  "mcpServers": {
    "tracker": {
      "type": "http",
      "url": "https://mcp.tracker.yandex.net/mcp",
      "headers": {
        "Authorization": "OAuth <token>",
        "X-Collab-Org-ID": "<organization_id>",
        "Accept": "application/json, text/event-stream"
      }
    }
  }
}
```

## Limitations {#limitations}

- An assistant does not receive some issues even if you can view them in the web interface. This happens if the queue security level is set to protect confidential data or the issue has the `secret` component. Instead of data, the server returns the issue key and the `restricted` flag.
- Attachment content is not transferred. The assistant receives metadata and a download link that is valid for 5 minutes. Files uploaded through MCP must not exceed 256 KiB; add larger files through the web interface.
- Bulk operations are asynchronous. After sending an operation, the assistant must wait for completion by checking its status.
- The tool catalog is sent to the client with every request and uses context. Disable unnecessary tools in your client.
- Queue forms can only be read; you cannot submit a form through the MCP server.
- When reading a trigger, the server does not return webhook credentials. Specify them again when you update an action.

## Security {#security}

- Give the token only the permissions it needs: an assistant can perform every action available to the token owner.
- Enable confirmation for calls that modify data. The tools include irreversible object deletion and bulk operations.
- Store only an environment variable reference in the client configuration, not the token itself. `.mcp.json` and `.codex/config.toml` files can be committed to a repository.
- Tokens and issue data are not written to server logs.

## Troubleshooting {#troubleshooting}

| **Symptom** | **Cause and solution** |
| --- | --- |
| Every call returns `403 Organization is not available` | The organization ID is missing. Add the `X-Collab-Org-ID` header. |
| Every request returns `404` | The `/api/mcp` path was used for the public server. Use `https://mcp.tracker.yandex.net/mcp`. |
| A request returns `401` | The token has expired or the authorization scheme is incorrect. Use `OAuth <token>` for OAuth and `Bearer <IAM_token>` for an IAM token. |
| The client cannot connect | Add the `Accept: application/json, text/event-stream` header. |
| A local test environment returns a certificate error | The environment may use a self-signed certificate. For debugging, start the client with `NODE_TLS_REJECT_UNAUTHORIZED=0`. |
| An issue is visible in the web interface, but the server returns `restricted` | The issue export policy applies. See [Limitations](#limitations). |
| The response contains `applied: null` | Tracker did not confirm the write. Check the result by reading it and do not retry blindly: for example, a worklog could be duplicated. |

## See also {#see-also}

- [Tracker CLI](https://yandex.com.tr/support/tracker/en/user/cli.md)