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 with automatic client registration via CIMD
Remote client that supports OAuth but not CIMD	OAuth authorization with a manually registered OAuth client
Remote client that doesn't support OAuth	Token-based authorization with a permanent token in the HTTP `Authorization` header
Local client that expects a local stdio server	OAuth authorization through `mcp-remote`, or token-based authorization with a permanent token

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 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.
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.

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.

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.

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.

To connect a remote MCP client application with OAuth authorization:

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.
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.
Follow the prompts in your AI tool to start authorization.
On the authorization page that opens, approve access for the AI tool.
Return to your AI tool and finish the connection setup.
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.

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.

To connect a remote MCP client application using a permanent token:

Generate a permanent token for your YouTrack account, selecting YouTrack as the scope. For specific instructions, see Create a Permanent Token.

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 <token>`, where the value for the `<token>` is the permanent token you generated for your YouTrack account.

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.

                    claude mcp add --header "Authorization: Bearer <token>" --transport http youtrack <youtrack-mcp-endpoint-url>
                

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.
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.

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 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.

To connect YouTrack to ChatGPT:

In ChatGPT, open Settings > Security and login and turn on Developer mode.
Open Plugins and click the plus button.
Enter a name for the plugin and add your YouTrack MCP endpoint URL as the MCP server URL.
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.
Complete the connection details and create the plugin.
When ChatGPT opens the YouTrack authorization page, approve access.
Return to ChatGPT and confirm that the YouTrack plugin is connected.
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.

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 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.

To connect YouTrack using a custom connector for a Claude Team or Enterprise plan:

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.
Open Customize > Connectors, find the YouTrack connector, and click Connect.
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.
Complete the setup and approve access in YouTrack.
Return to Claude, confirm that the connector is active, and test it with a read-only request.

To connect YouTrack using a custom connector for an individual Claude plan:

Open Customize > Connectors, click the plus button, and select Add custom connector.
Enter YouTrack as the connector name and provide the YouTrack MCP endpoint URL.
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.
Complete the setup and approve access in YouTrack.
Confirm that the connector is active and test it with a read-only request.

Local MCP Client Connections

Use this setup for a local AI tool that expects a local 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 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.

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.

To connect a local MCP client using CIMD:

Ask a YouTrack system administrator to enable automatic OAuth client registration as described in Set Up OAuth Client Registration.
Choose a callback port for mcp-remote. The callback URI is http://localhost:<callback-port>/oauth/callback.
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:<callback-port>/oauth/callback in its redirect_uris property.
For details, see Client ID Metadata Documents in the mcp-remote documentation.
Add the following mcp-remote reference to the configuration for your AI tool:
{ "mcpServers": { "youtrack": { "command": "npx", "args": [ "-y", "mcp-remote", "<youtrack-mcp-endpoint-url>", "<callback-port>", "--client-metadata-url", "<oauth-client-metadata-url>" ] } } }
For <youtrack-mcp-endpoint-url>, 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.
Restart or reload the local AI client. When mcp-remote opens the authorization page in a browser, approve access.
Return to your AI tool, confirm that the YouTrack tools are available, and test the connection with a read-only request.

To connect a local MCP client using a manually registered OAuth client:

Choose a callback port for mcp-remote. The callback URI is http://localhost:<callback-port>/oauth/callback.
Ask a YouTrack system administrator to create an OAuth client as described in Create an OAuth Client Manually. 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.
Store the generated OAuth client information in a JSON file on your computer:
{ "client_id": "<oauth-client-id>", "client_secret": "<oauth-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.
Add the following mcp-remote reference to the configuration for your AI tool:
{ "mcpServers": { "youtrack": { "command": "npx", "args": [ "-y", "mcp-remote", "<youtrack-mcp-endpoint-url>", "<callback-port>", "--static-oauth-client-info", "@<absolute-path-to-oauth-client-info-file>" ] } } }
For details, see Static OAuth Client Information in the mcp-remote documentation.
For <youtrack-mcp-endpoint-url>, 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.
Restart or reload the local AI client. When mcp-remote opens the authorization page in a browser, approve access.
Return to your AI tool, confirm that the YouTrack tools are available, and test the connection with a read-only request.

Choose token-based authorization when you need to provide a token directly in the local connection configuration.

To connect a local MCP client application using a permanent token:

Generate a permanent token for your YouTrack account, selecting YouTrack as the scope. For specific instructions, see Create a Permanent Token.
Store Bearer <token> 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.
Add the following reference to the configuration for your AI tool:
{ "mcpServers": { "youtrack": { "command": "npx", "args": [ "-y", "mcp-remote", "<youtrack-mcp-endpoint-url>", "--header", "Authorization:${AUTH_HEADER}" ] } } }
- For <youtrack-mcp-endpoint-url>, 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.
Restart or reload the local AI client, confirm that the YouTrack tools are available, and test the connection with a read-only request.

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.

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 in the Developer Portal for YouTrack and Hub.

17 September 2026