# Remote MCP Server Model Context Protocol (MCP) is a new standard that lets apps like chatbots and other AI tools talk to other services, like YouTrack, in a consistent and safe way. The YouTrack MCP server gives these tools real-time access to read and update issues in YouTrack, using your own account permissions. It includes a set of built-in tools you can use to find, create, and update things like issues and comments. YouTrack supports connections to local and remote clients, which means you can use whichever connection type is supported by your AI tools. ## Choose a Connection Type Choose a connection type and authorization method based on the capabilities of your AI client. | Client setup | Authorization | | --- | --- | | Remote client that supports OAuth and CIMD | [OAuth authorization](#remote-mcp-oauth) with [automatic client registration via CIMD](oauth-clients.html#automatic-oauth-client-registration) | | Remote client that supports OAuth but not CIMD | [OAuth authorization](#remote-mcp-oauth) with a [manually registered OAuth client](oauth-clients.html#create-oauth-client) | | Remote client that doesn't support OAuth | [Token-based authorization](#remote-mcp-token) with a [permanent token](manage-permanent-token.html#obtain-permanent-token) in the HTTP `Authorization` header | | Local client that expects a local stdio server | [OAuth authorization through mcp-remote](#local-mcp-oauth), or [token-based authorization with a permanent token](#local-mcp-token) | > **Note: Review Permissions and Data Access** > Review the permissions assigned to the account that you use for the connection. The YouTrack MCP server applies these permissions to every request, so the client can access only the data available to the authenticated user. Review tool calls carefully before you confirm actions that create or update content. > > > > Before you connect a remote AI client, review the provider's data handling policies and your organization's requirements. The client or its provider can process your prompts and the YouTrack data returned to the client. ## Set Up OAuth Client Registration Before you connect a remote or local MCP client with OAuth, determine which client registration method it supports. Ask a YouTrack system administrator to complete the corresponding setup, then approve access with your own YouTrack account when you connect. * For a client that supports CIMD, ask a system administrator to open ![](https://resources.jetbrains.com/help/img/youtrack/2026.2/settings.svg) `Administration > Access Management > OAuth Clients` and enable Allow automatic OAuth client registration via CIMD. After the administrator enables this setting, connect the compatible client with the YouTrack MCP endpoint URL. For details, follow [Automatic OAuth Client Registration](oauth-clients.html#automatic-oauth-client-registration). * For a client that doesn't support CIMD, obtain its redirect URL and other required OAuth settings from the AI client provider. Ask a system administrator to create an OAuth client manually, then enter the generated client ID and, for a confidential client, the client secret in the AI client. For instructions, follow [Create an OAuth Client](oauth-clients.html#create-oauth-client). Check the documentation for your MCP client to determine whether it supports CIMD and which OAuth settings it requires. For technical details about OAuth endpoints, supported flows, preregistered clients, and CIMD, see [OAuth 2.0 Authorization in the Developer Portal](https://www.jetbrains.com/help/youtrack/devportal/OAuth-authorization-in-youtrack.html). ## Remote MCP Client Connections Use a remote connection for cloud-based applications that communicate over HTTP. Examples include automation tools like n8n and OpenAI's Agent Kit, integration platforms like Zapier and Make, or coding agents like Claude Code, Codex, or Junie. Choose OAuth authorization when your AI tool supports a browser-based authorization flow. Choose token-based authorization only when the tool can't complete OAuth authorization. Before you start, verify that the client accepts a remote MCP endpoint URL and supports either OAuth authorization or custom HTTP authorization headers. Check whether the client supports CIMD or requires manually registered OAuth client credentials. > **Note: Check Organization-managed AI Tool Settings** > If your AI tool is managed by an organization or workspace, ask its administrator whether they need to enable or approve custom connectors before you add YouTrack. Configure this access in the AI tool, not in YouTrack. OAuth: Choose OAuth to authorize the client in a browser without creating a permanent token. Approve access with the YouTrack account whose permissions you want the client to use. Procedure: To connect a remote MCP client application with OAuth authorization: 1. Enter the YouTrack MCP endpoint URL in the settings for your AI tool. Use the base URL for your YouTrack site, followed by `/mcp`. For example, `https://youtrack.mycompany.com/mcp`. 2. If your AI tool asks for OAuth client credentials, enter the client ID and, for confidential clients, the client secret from the manually created OAuth client. 3. Follow the prompts in your AI tool to start authorization. 4. On the authorization page that opens, approve access for the AI tool. 5. Return to your AI tool and finish the connection setup. 6. Confirm that the connection is active and that the client can list the available YouTrack tools. Test the connection with a read-only request, for example, ask the client to find issues assigned to you. Token-based: Choose token-based authorization only when the client can't complete OAuth. Generate a permanent token in YouTrack and provide it to the AI tool as an HTTP authorization header. Procedure: To connect a remote MCP client application using a permanent token: 1. Generate a permanent token for your YouTrack account, selecting YouTrack as the scope. For specific instructions, see [Create a Permanent Token](manage-permanent-token.html#obtain-permanent-token). 2. Enter the following variables in the settings for your AI tool: | Variable | Description | | --- | --- | | YouTrack MCP endpoint | Enter the base URL for your YouTrack site, followed by `/mcp`. For example, `https://youtrack.mycompany.com/mcp`. | | HTTP header | Provide the authorization token to be used in the header for HTTP requests to the YouTrack MCP endpoint. For example, `Authorization: Bearer `, where the value for the `` is the permanent token you generated for your YouTrack account. | 3. Confirm that the connection is active and test it with a read-only request. Here's a sample command that shows you how to connect to Claude Code. When using it, replace the placeholders with the MCP endpoint URL for your YouTrack site and your permanent token. ```BASH claude mcp add --header "Authorization: Bearer " --transport http youtrack ``` > **Note: Resolve Remote Connection Problems** > * If the client reports that automatic registration isn't supported, ask a YouTrack system administrator to enable CIMD. If the client doesn't support CIMD, use a manually registered OAuth client instead. > > * If the client can't find the server, check that the URL uses the base URL configured for your YouTrack site and ends with `/mcp`. Use HTTPS when the client connects to your site over the public internet. > > * If authorization fails, verify the OAuth client settings and redirect URL or delete the connection in the AI client and authorize it again. > > * If the connection succeeds but expected data isn't available, verify that the authorizing user has permission to access that data in YouTrack. Check whether the relevant projects or issues are hidden from AI tools. For details, see [Check Data Visibility](#mcp-data-visibility). > > * If you use a permanent token and receive an authorization error, verify that the token has the YouTrack scope and hasn't been deleted. ### OAuth Setup Examples for Common AI Clients Complete the applicable OAuth client registration in YouTrack, then add the YouTrack MCP endpoint URL to your AI tool. ChatGPT: Use the following procedure to create a remote OAuth connection. Before you start, verify that your ChatGPT plan and workspace settings provide access to Developer mode and plugins. Check [Developer mode](https://developers.openai.com/api/docs/guides/developer-mode) for current ChatGPT instructions and availability. Make sure that ChatGPT can reach the MCP endpoint for your YouTrack Server site over the public internet using HTTPS. If your site is available only through a private network or VPN, use a secure network connection method supported by ChatGPT or a compatible local MCP client. Procedure: To connect YouTrack to ChatGPT: 1. In ChatGPT, open `Settings > Security and login` and turn on Developer mode. 2. Open Plugins and click the plus button. 3. Enter a name for the plugin and add your YouTrack MCP endpoint URL as the MCP server URL. 4. If ChatGPT asks for OAuth client credentials, enter the client ID and, for a confidential client, the client secret from the manually registered YouTrack OAuth client. 5. Complete the connection details and create the plugin. 6. When ChatGPT opens the YouTrack authorization page, approve access. 7. Return to ChatGPT and confirm that the YouTrack plugin is connected. 8. Enable the plugin in a conversation and test it with a read-only request, for example, ask ChatGPT to find issues assigned to you. If Developer mode or Plugins isn't available, contact your ChatGPT workspace administrator. > **Warning:** > YouTrack MCP tools can create and update data as well as read it. Review tool calls before you confirm actions that modify YouTrack content. Claude: Add your YouTrack Server site to Claude as a custom connector. Don't use the verified connector in the Claude Connector Directory, as it doesn't accept YouTrack Server URLs. Check [Get started with custom connectors using remote MCP](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) for current Claude instructions. | YouTrack site | Connection method | | --- | --- | | Publicly reachable YouTrack Server site | Configure a custom connector. | | YouTrack Server site available only through a private network or VPN | Use a compatible local MCP client. Claude's cloud infrastructure can't reach a private YouTrack site. | To connect using a custom connector, follow the procedure for your Claude plan. > **Warning:** > Before you configure a custom connector, make sure that your YouTrack site is reachable from the public internet. Claude connects from Anthropic's cloud infrastructure and can't reach a site that is available only through a private network or VPN. Team or Enterprise: Procedure: To connect YouTrack using a custom connector for a Claude Team or Enterprise plan: 1. Ask a Claude Owner or Primary Owner to open `Organization settings > Connectors` and add a custom web connector named YouTrack using the YouTrack MCP endpoint URL. 2. Open `Customize > Connectors`, find the YouTrack connector, and click Connect. 3. If Claude asks for OAuth credentials, open Advanced settings and enter the client ID and, for confidential clients, the client secret from the manually created YouTrack OAuth client. 4. Complete the setup and approve access in YouTrack. 5. Return to Claude, confirm that the connector is active, and test it with a read-only request. Individual: Procedure: To connect YouTrack using a custom connector for an individual Claude plan: 1. Open `Customize > Connectors`, click the plus button, and select Add custom connector. 2. Enter YouTrack as the connector name and provide the YouTrack MCP endpoint URL. 3. If Claude asks for OAuth credentials, open Advanced settings and enter the client ID and, for confidential clients, the client secret from the manually created YouTrack OAuth client. 4. Complete the setup and approve access in YouTrack. 5. Confirm that the connector is active and test it with a read-only request. > **Note: Resolve Claude Connection Problems** > * If Claude rejects the YouTrack Server URL in the verified connector, add YouTrack as a custom connector instead. Use the base URL for your YouTrack site followed by `/mcp`. > > * If Claude asks for OAuth client credentials, ask a YouTrack system administrator to register an OAuth client manually. Enter the generated client ID and, for a confidential client, the client secret in Advanced settings. > > * If Claude can't reach the custom connector, verify that your YouTrack Server site is reachable from the public internet. For a site available only through a private network or VPN, use a compatible local MCP client instead. ## Local MCP Client Connections Use this setup for a local AI tool that expects a local [stdio](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#stdio) server. The `mcp-remote` proxy runs on your computer and forwards requests from the local client to the remote YouTrack MCP endpoint. If your local tool supports remote MCP connections over HTTP directly, use the instructions for [remote clients](#remote-mcp-client) instead. Use OAuth authorization when your local tool or proxy can open a browser-based authorization flow. Use token-based authorization when you need to provide a token directly in the local configuration. > **Note: Install the Prerequisites** > Install [Node.js](https://nodejs.org/en/download) 18 or later and make sure that the `npx` command is available. Use the open-source [mcp-remote proxy](https://github.com/geelen/mcp-remote) in the connection configuration. > > > > Check that your local client lets you add a stdio MCP server by specifying a command and arguments. Consult the client documentation to find the location and format of this configuration. OAuth: Choose OAuth to authorize the local client in a browser without adding a permanent token to its configuration. Approve access with the YouTrack account whose permissions you want the client to use. YouTrack doesn't support OAuth Dynamic Client Registration. Configure `mcp-remote` with either a Client ID Metadata Document (CIMD) URL or the credentials for a manually registered OAuth client. Choose the procedure that corresponds to the OAuth client registration method. CIMD: Procedure: To connect a local MCP client using CIMD: 1. Ask a YouTrack system administrator to enable automatic OAuth client registration as described in [Set Up OAuth Client Registration](#prepare-oauth-access). 2. Choose a callback port for `mcp-remote`. The callback URI is `http://localhost:/oauth/callback`. 3. Prepare or obtain an OAuth client metadata document that describes `mcp-remote` as the OAuth client. * Host the document at an HTTPS URL that includes a path. * Include `http://localhost:/oauth/callback` in its `redirect_uris` property. For details, see [Client ID Metadata Documents](https://github.com/geelen/mcp-remote#client-id-metadata-documents) in the `mcp-remote` documentation. 4. Add the following `mcp-remote` reference to the configuration for your AI tool: ```JSON { "mcpServers": { "youtrack": { "command": "npx", "args": [ "-y", "mcp-remote", "", "", "--client-metadata-url", "" ] } } } ``` 5. For ``, use the base URL for your YouTrack site followed by `/mcp`. For example, use `https://youtrack.mycompany.com/mcp`. If the base URL uses HTTP on a trusted private network, add `--allow-http` to the `args` array. 6. Restart or reload the local AI client. When `mcp-remote` opens the authorization page in a browser, approve access. 7. Return to your AI tool, confirm that the YouTrack tools are available, and test the connection with a read-only request. Manual Registration: Procedure: To connect a local MCP client using a manually registered OAuth client: 1. Choose a callback port for `mcp-remote`. The callback URI is `http://localhost:/oauth/callback`. 2. Ask a YouTrack system administrator to create an OAuth client as described in [Create an OAuth Client Manually](oauth-clients.html#create-oauth-client). Ask the administrator to enable the Authorization Code flow and add the callback URI to the list of redirect URIs. `mcp-remote` uses PKCE when it completes this flow. 3. Store the generated OAuth client information in a JSON file on your computer: ```JSON { "client_id": "", "client_secret": "" } ``` For a public client, omit the `client_secret` property. If the file contains a client secret, restrict access to the file and don't commit it to version control. 4. Add the following `mcp-remote` reference to the configuration for your AI tool: ```JSON { "mcpServers": { "youtrack": { "command": "npx", "args": [ "-y", "mcp-remote", "", "", "--static-oauth-client-info", "@" ] } } } ``` For details, see [Static OAuth Client Information](https://github.com/geelen/mcp-remote#static-oauth-client-information) in the `mcp-remote` documentation. 5. For ``, use the base URL for your YouTrack site followed by `/mcp`. For example, use `https://youtrack.mycompany.com/mcp`. If the base URL uses HTTP on a trusted private network, add `--allow-http` to the `args` array. 6. Restart or reload the local AI client. When `mcp-remote` opens the authorization page in a browser, approve access. 7. Return to your AI tool, confirm that the YouTrack tools are available, and test the connection with a read-only request. Token-based: Choose token-based authorization when you need to provide a token directly in the local connection configuration. Procedure: To connect a local MCP client application using a permanent token: 1. Generate a permanent token for your YouTrack account, selecting YouTrack as the scope. For specific instructions, see [Create a Permanent Token](manage-permanent-token.html#obtain-permanent-token). 2. Store `Bearer ` in an environment variable named `AUTH_HEADER` or in the secure credential store provided by your AI client. Don't commit the token to version control or include it in a shared configuration file. 3. Add the following reference to the configuration for your AI tool: ```JSON { "mcpServers": { "youtrack": { "command": "npx", "args": [ "-y", "mcp-remote", "", "--header", "Authorization:${AUTH_HEADER}" ] } } } ``` * For ``, enter the full YouTrack MCP endpoint URL for your site. * Make sure that the environment used to start the AI client contains the `AUTH_HEADER` variable. 4. Restart or reload the local AI client, confirm that the YouTrack tools are available, and test the connection with a read-only request. > **Note: Resolve Local Connection Problems** > * If the client can't run `npx`, verify that Node.js 18 or later is installed and available in the environment used to start the client. > > * If authorization fails because Dynamic Client Registration isn't supported, configure `mcp-remote` with either `--client-metadata-url` for CIMD or `--static-oauth-client-info` for a manually registered client. > > * If authorization doesn't open in a browser or the callback fails, check the callback URL and port in the OAuth client registration and `mcp-remote` configuration. > > * If a token-based connection returns an authorization error, verify that `AUTH_HEADER` contains `Bearer`, followed by a space and the permanent token. > > * If the configuration changed but the tools don't appear, completely restart the local AI client. ## Optional Parameters Add optional query parameters to the MCP endpoint URL to control how your AI tools interact with YouTrack. Include one or more of the following parameters in the URL for your connection. | Parameter | Description | | --- | --- | | tools | Set this parameter to a comma-separated list of tool names that the MCP server should return on a `tools/list` request. For example, `/mcp?tools=search_issues,get_issue`. Use this parameter to help prevent unintentional overuse of your AI quota, especially for expensive requests. | | ignoreTools | Set this parameter to a comma-separated list of tool names to exclude from the `tools/list` response. For example, `/mcp?ignoreTools=find_user,manage_issue_tags`. Use this parameter to help prevent unintentional overuse of your AI quota, especially for expensive requests. | | customToolPackages | Set this parameter to a comma-separated list of app packages whose custom tools you want to make available to the MCP server. Request each package specifically by name. For example, `/mcp?customToolPackages=app-name1,app-name2` where `app-name1` and `app-name2` are the names of apps that define custom tools. | | enableToolOutputSchema | Set this parameter to `true` to make the server return a JSON Schema that describes the tool output. MCP clients with version 2025-06-18 and above can add this output to the LLM context for tool calling. For example, `/mcp?enableToolOutputSchema=true`. All the predefined AI tools for the YouTrack MCP server return output schemas. Output schemas are also supported in custom tools. | ## AI Tools Use the predefined MCP tools to work with issues, articles, projects, users, and time tracking. Start using them as soon as you connect your AI client; you don't need to install them separately. > **Note: Check Data Visibility** > MCP tools can return only the data available to the authenticated user. YouTrack can also apply AI-specific visibility restrictions that hide projects and issues from AI tools. As a result, an item that you can view in YouTrack might not appear in an MCP response. ### Issue Use issue tools to search, create, update, and manage issues. Create tasks, link related issues, add comments, and update progress directly from your AI client. | Name | Description | Sample Prompt | | --- | --- | --- | | `search_issues` | Searches for issues using YouTrack’s query language. The query can combine attribute filters, keywords, and free text. Returns basic information for matching issues, including the issue ID, summary, project, resolved, reporter, created, updated. For full details, use `get_issue`. The response is paginated using the specified offset and limit. | Find all open bugs assigned to me in the Mobile App project. | | `get_issue_fields_schema` | Returns the JSON schema for custom fields in the specified project. Must be used to provide relevant custom fields and values for `create_issue` and `update_issue` actions. | Which fields are required to create issues in the Website Redesign project? | | `create_issue` | Creates a new issue in the specified project. * Use `get_issue_fields_schema` to discover `customFields` and their possible values for the target project. Important: some fields may be required for issue creation. * Use the optional `permittedUsers` and `permittedGroups` arguments to restrict who can view the issue. Returns the ID of the created issue and URL that opens the issue in a web browser. Use `get_issue` to get the full issue details . | Create a new issue in the Backend API project with the summary "Fix authentication timeout" with a priority of High and assign it to @alex. Restrict the visibility to the Security Team group. | | `create_draft_issue` | Creates a new issue draft in the specified project. Draft issues are only visible to the current user and can be edited using `update_issue`. Returns the ID assigned to the issue draft and a URL that opens the draft in a web browser. | Start a draft issue in the Marketing Site project with the summary "Revise homepage hero section". | | `update_issue` | Updates an existing issue and its fields. Can also be used to star issues and add votes. | Update issue WEB-132 by changing its state to In Progress and adding the label "frontend". | | `get_issue` | Returns detailed information for an issue or issue draft, including the summary, description, URL, project, reporter (username), tags, votes, and custom fields. The `customFields` output property provides more important issue details, including Type, State, Assignee, Priority, Subsystem, and so on. Use `get_issue_fields_schema` for the full list of custom fields and their possible values. | Show me all details for issue ID BACK-249. | | `change_issue_assignee` | Sets the value for the Assignee field in an issue to the specified user. | Reassign issue DEV-102 to @julia. | | `add_issue_comment` | Adds a new comment to the specified issue. Supports Markdown. Use the optional `permittedUsers` and `permittedGroups` arguments to restrict who can view the comment. | Add a comment to issue APP-56: "Great progress. Please include the API documentation before closing". Make the comment visible to the Feature Development team. | | `get_issue_comments` | Returns a list of issue comments with detailed information for each. The response is paginated using the specified offset and/or limit. | List all comments for issue UX-87. | | `get_saved_issue_searches` | Returns saved searches marked as favorites by the current user. The output search queries can be used in `search_issues`. The response is paginated using the specified offset and/or limit. | Show me my saved searches. | | `manage_issue_tags` | Adds a tag to or removes a tag from an issue. If a name is used, the first tag that matches the provided name is added. If no matching tags are found, an error message with suggestions for similar tags is returned. When successful, it returns the ID of the updated issue and the updated list of issue tags. | Add the tag "urgent" to issue API-144. | | `link_issues` | Links two issues with the specified link type. Returns updated link counts for all target issue link types. | Link issue DOCS-12 to issue DEV-99 as "relates to". | ### Article Use article tools to search, read, create, and manage documentation stored in YouTrack. Organize information, draft new guides, and keep existing content up to date from your AI client. | Name | Description | Sample Prompt | | --- | --- | --- | | `create_article` | Creates a new article in the specified project. Returns the created article ID and URL. Use the optional `permittedUsers` and `permittedGroups` arguments to restrict who can view the article. | Copy the last output from this chat and create an article in the Compliance project. Restrict the visibility of the article to the Legal team. | | `update_article` | Updates an existing article. You can update the title, content, and parent article. Returns the updated article ID and URL. | Copy the last output from this chat and add it to the end of the Trends to Watch article. | | `get_article` | Returns detailed information for an article, including title, content, sub-articles, tags, and visibility settings. Supports line-by-line scrolling for long articles. | Show me the full content of the Onboarding Guide article, including any sub-articles. | | `search_articles` | Searches for articles in the knowledge base using YouTrack’s query language. The query can combine attribute filters, keywords, and free text. Returns basic information about the article, including its ID, title, URL, parent article, and the lines where content matching the query was found. For full details, use `get_article`. The response is paginated using the specified offset and limit. | Search for articles about API Authentication in the Developer Docs project created by @sarah. | ### Project Use project tools to locate projects by name, retrieve their configurations, and prepare to create issues or drafts. | Name | Description | Sample Prompt | | --- | --- | --- | | `find_projects` | Finds projects whose names contain the specified substring (case-insensitive). Returns minimal information (ID and name) to help pick a project for `get_project`. The response is paginated using the specified offset and/or limit. | Find all projects with "CRM" in the name. | | `get_project` | Retrieves full details for a specific project. | Get full details for the "Customer Portal" project. | ### Group Use group tools to find user groups or project teams by name and list their members. | Name | Description | Sample Prompt | | --- | --- | --- | | `find_user_groups` | Finds user groups or project teams whose names contain the specified substring (case-insensitive). The response is paginated using the specified offset and/or limit. | List all groups that include the word "Design". | | `get_user_group_members` | Lists users who are members of a specified group or project team. Project teams are essentially groups that are always associated with a specific project. The response is paginated using the specified offset and/or limit. | Show me the list of members in the QA Engineers group. | ### User Use user tools to find a user by email or username or retrieve details about the authenticated account. Use the results to confirm identity, assign ownership, or personalize automated actions. | Name | Description | Sample Prompt | | --- | --- | --- | | `find_user` | Finds users by username or email. Returns profile data for the matching user. This includes the username, full name, email, and local time zone. | Find the user with email alex.rocha@company.com. | | `get_current_user` | Returns details about the currently authenticated user (me): username, email, full name, time zone. | Show my account details. | ### Time Tracking Use time tracking tools to log work items for specific issues and keep accurate records of time spent on project activities. | Name | Description | Sample Prompt | | --- | --- | --- | | `log_work` | Adds a work item (spent time) to the specified issue. You can specify the duration in minutes, optional date, work type, description, and optional work item attributes. Use `get_project` to retrieve the `workTypes` and `workItemAttributesSchema` for the target project. | Log 90 minutes of work on issue DEV-203 with the description "Refactored payment module". | ### Custom AI Tools Create custom MCP tools when the predefined tools don't cover your use case. Add the scripts to an app package and make them available to users who connect to the YouTrack MCP server. Follow [Custom MCP Tools](https://www.jetbrains.com/help/youtrack/devportal/custom-ai-tools.html) in the Developer Portal for YouTrack and Hub.