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

Using the MCP server, an assistant can:

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

Connect the server

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. Use an IAM token for a Yandex Cloud organization; it is valid for up to 12 hours.
2. Open Administration → Organizations and copy the value of the ID field on the organization card. If the card is titled Yandex 360 for Business, pass the ID in the X-Org-ID header; if it is titled Yandex Cloud Organization, pass it in the X-Cloud-Org-ID header.
3. Add the MCP server configuration to your AI assistant settings. Specify the URL and headers from the table below.
4. Verify the connection. For example, in Codex, run /mcp: the server and its tools should appear in the list. The tool list loads without checking the token, so then ask the assistant to run a simple request, such as listing queues.

Connection parameters:

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.

The examples use the X-Org-ID header. If you copied the ID from the Yandex Cloud Organization card, use X-Cloud-Org-ID instead.

Codex configuration

For an OAuth token, 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. For an IAM token, set the variable to Bearer <IAM_token>.

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

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

Before starting Codex, set the environment variables:

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

Claude Code configuration

Single quotes preserve the environment variable reference in .mcp.json instead of replacing it with the token value. Specify the server name and URL before the --header options, otherwise the command fails:

export TRACKER_OAUTH_TOKEN="<token>"

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

Other MCP client configuration

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

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

If the client supports environment variable substitution, use a variable reference in the Authorization header instead of the token.

Limitations

• An assistant does not receive the data of some issues even if you can view them in the web interface. This happens if the Access for AI tools option in the queue settings is set to Deny. Instead of data, the server returns the issue key and the restricted flag. The assistant can still modify such issues.
• 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 on connection and uses the assistant's 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 the trigger's actions.

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 the text of issues and comments are not written to server logs. The logs contain API request paths and parameters, such as issue keys, uploaded file names, and search strings.

Troubleshooting

See also

• Tracker CLI