Module 3, Lesson 6: Set Up Claude Code + YouTrack

In this lesson, I'm picking up from the implementation roadmap we wrote in Module 3, Lesson 5 and connecting everything to our project tracking system — YouTrack — so that Claude Code can read and write issues directly.

Before We Start

Here's what I'd expect you to have under your belt before this lesson:

From previous lessons:

• You should have your prioritisation document and implementation roadmap already written (Module 3, Lessons 4 and Lesson 5)
• You should have Claude Code installed and be able to run it from your terminal (Module 3, Lesson 3)
• Your project should be open in WebStorm with your specs folder already in place

Tools / setup you'll need:

• YouTrack account — free tier is fine; sign up at jetbrains.com/youtrack if you haven't already
• Claude Code installed and working in your terminal
• WebStorm (or VS Code) open with your project folder
• Your .mcp.json file — we'll create this together in the lesson

By the end of this lesson, you'll:

• Have a YouTrack project set up and configured with the right custom fields
• Have a .mcp.json config file in your project root that connects YouTrack to Claude Code
• Know how to start Claude Code so it loads only the MCP servers for that specific project
• Have verified the connection by having Claude Code create a test issue in YouTrack

About This Lesson

Duration: ~14 minutes video + ~20 minutes setup
Skill Level: Intermediate
What You'll Build: A live, bidirectional connection between Claude Code and YouTrack — your AI coding agent can now read from and write to your project tracker.

This lesson is about plumbing. It's not glamorous, but once this connection is solid, everything in the next phase becomes dramatically smoother. You're not just setting up a tool — you're wiring up the system that will let Claude Code act as a real collaborator on your project, not just a standalone chat assistant.

Watch the Lesson

What We're Covering

Here's what I'm walking you through in this lesson and why it matters:

• Setting up YouTrack — creating your project, adding the right custom fields, and getting your Agile board ready
• Generating a YouTrack API token — the key that lets Claude Code talk to your tracker
• Creating the .mcp.json config — how I wire up MCP servers on a per-project basis (and why I do it this way instead of globally)
• The Claude Code startup command — the specific flag you need to load only the MCP servers for your project
• Verifying the connection — having Claude Code create a real issue in YouTrack as a live test

1. Let's Set the Scene (~0:00)

At this point you should have your specs and implementation roadmap written. If you open WebStorm and look at your project, you should see your specs folder sitting there with the work we did in Module 3, Lessons 2 through 5.

Now we're going into the project planning phase. The reason we plan in a tracker — rather than just keeping everything in files — is so we know where we are at any given point. When Claude Code is doing the actual coding later, we're not just vibing and hoping for the best. We've done the hard thinking upfront, and now we want somewhere to track the progress of all that work.

This is also useful if you're collaborating with other people, or if you're scoping this out to hand off to someone else. Either way — you want it well structured, and that's what YouTrack gives us.

2. Setting Up YouTrack (~0:53)

2.1 Create Your Account

Head to jetbrains.com/youtrack and sign up. It's straightforward. Once you're in, you'll land in a dashboard that's mostly empty for now.

2.2 Create a Kanban Project

Don't do anything on the dashboard just yet. The first thing you want to do is create a project:

1. Go to Projects → New Project
2. Choose Kanban as the project type
3. Give your project a name — I'm calling mine Notero Development (yours will be whatever your app is called)
4. Give it a short code — this is the project ID prefix for all your issues (mine is NERT)

2.3 Add the Type Custom Field

Once your project is created and you're inside it, go to Custom Fields and check what's already there. You should see Priority and Assignee by default. I also add Type:

1. Click Add fields to project → Use existing
2. Search for Type and add it
3. By default it comes with: Bug, Statistics, Usability, Performance — that's fine, leave it

This makes it easier for both you and Claude to categorise work properly later. You don't need to touch anything else in Custom Fields for now.

2.4 Check the Agile Board

Go to Agile Boards and take a look. It'll show the default columns (Open, In Progress, Done, etc.). Leave it as is for now — I'll cover board organisation in the next phase. For now you just need to confirm the project is set up and the board is there.

3. Connecting YouTrack to Claude Code (~4:10)

This is the core of the lesson. Two things need to happen: you need a YouTrack API token, and you need a .mcp.jsonfile in your project root that tells Claude Code how to connect.

3.1 Generate an API Token in YouTrack

1. In YouTrack, click your profile name (top right — probably says "admin" by default)
2. Go to Profile → Account Security → Tokens
3. Click New Token and give it a name — I call mine MCP
4. Copy the token and save it somewhere safe immediately — you won't see it again

3.2 Create the .mcp.json File

In WebStorm, click on your project folder, choose New File, and name it .mcp.json. This file lives at the top level of your project — not inside any subfolder.

Here's the config you want:

{
  "mcpServers": {
    "youtrack": {
      "type": "http",
      "url": "https://<username>.youtrack.cloud/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

Replace two things:

• <username> → your YouTrack instance name (the subdomain of your YouTrack URL — mine is deletosh)
• <token> → the token you just generated

So a real example looks like:

{
  "mcpServers": {
    "youtrack": {
      "type": "http",
      "url": "https://deletosh.youtrack.cloud/mcp",
      "headers": {
        "Authorization": "Bearer perm:abc123yourtokenhere"
      }
    }
  }
}

Save the file.

3.3 Start Claude Code with Project-Specific MCP

This is the key part — and the reason I keep MCP config per-project rather than globally.

When you just type claude in your terminal, Claude Code starts with whatever MCP servers you've set up globally. The problem is, if you've got Figma, Obsidian, and half a dozen other MCPs installed globally from Claude Desktop, Claude Code gets confused about which tools to use.

My approach: I start Claude Code and explicitly tell it which MCP config to load. Here's the command:

claude --strict-mcp-config --mcp-config .mcp.json

What this does:

• --strict-mcp-config — tells Claude Code to only load the MCP servers defined in the config file I specify. Nothing else.
• --mcp-config .mcp.json — points to the .mcp.json file in the current project directory

From this point on, whenever you start a Claude Code session on this project, use this command instead of just claude.

4. Verifying the Connection (~10:19)

4.1 Check MCP Servers Are Loaded

After you run the startup command, Claude Code opens in your terminal. Type:

/mcp

This shows you all the MCP servers that are currently loaded. You want to see YouTrack listed with status connected. If it's not there, or it shows an error, stop here and retrace the steps above before continuing.

4.2 Test with a Sample Issue

Once you can see YouTrack connected, do a quick sanity test. Type something like:

Using the YouTrack tool, create a sample issue in my project NERT

(Replace NERT with your actual project short code.)

Claude Code will ask you to confirm before it runs the tool — that's by design. Say yes. If everything is wired up correctly, you'll see it confirm the issue was created. Then flip over to YouTrack in your browser, refresh the project, and the issue should be sitting right there.

5. Watch Out For These

6. Practice

Exercise 1: Full Setup from Scratch

What to do: Close this guide and redo the entire setup flow from memory — YouTrack project, custom fields, token, .mcp.json, startup command. Use the guide only to check yourself at the end.

How you'll know it's working: You run /mcp inside Claude Code and see YouTrack as connected.

Exercise 2: Create and Delete Test Issues

What to do: Ask Claude Code to create three test issues in your YouTrack project with different types (Bug, Task, Feature). Then go into YouTrack manually and delete them.

What this is practising: Getting comfortable with the back-and-forth between Claude Code and YouTrack — you'll be doing a lot of this in the build phase.

7. You Should Be Able to Build This Now

With this lesson done, you can:

• Set up a YouTrack project for any new app you're building
• Wire Claude Code to that project via a project-specific MCP config
• Verify the connection is live before you start any real work

Check Yourself

• I have a YouTrack project created with a short code I know
• I have a .mcp.json in my project root with the correct URL and token
• I can start Claude Code with --strict-mcp-config --mcp-config .mcp.json
• Running /mcp shows YouTrack as connected
• I've created a test issue via Claude Code and confirmed it appeared in YouTrack

If Something's Not Working

The Short Version

Here's what I want you to walk away with:

• YouTrack is your project command centre — it's where all your issues live and where you'll track progress through the build phase.
• The .mcp.json file is the bridge — it tells Claude Code how to talk to YouTrack, and keeping it project-specific avoids a lot of headaches.
• Always start Claude Code with the full command — claude --strict-mcp-config --mcp-config .mcp.json — so it only loads the tools your project needs.
• Verify before you move forward — run /mcp, confirm YouTrack shows connected, create a test issue. Don't skip this.

Quick Reference

Claude Code Startup Command

claude --strict-mcp-config --mcp-config .mcp.json

.mcp.json Template

{
  "mcpServers": {
    "youtrack": {
      "type": "http",
      "url": "https://<your-username>.youtrack.cloud/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

Claude Code MCP Commands

/mcp          — lists all loaded MCP servers and their connection status

YouTrack Token Location

Profile → Account Security → Tokens → New Token

Resources

Links & Docs

• YouTrack — project tracking tool used in this course
• YouTrack MCP documentation — official docs (I use a different approach to what's shown here, but worth knowing it exists)
• Claude Code documentation — reference for Claude Code commands and flags

Tools Used

• YouTrack — free tier, sign up at jetbrains.com
• Claude Code — the agentic coding tool we're running in the WebStorm terminal

Questions I Get Asked

Q: Can I use a different project tracker — Jira, Linear, Asana?

You can, as long as it supports MCP. That's the only requirement. YouTrack has excellent MCP support and it integrates well with WebStorm, which is why I use it. But if your team is already on Jira or Linear and those tools have MCP support, the same principles apply — you'd just swap out the config in your .mcp.json.

Q: Do I need to keep the .mcp.json out of version control?

Good question. It contains your API token, so yes — add .mcp.json to your .gitignore if you're pushing this project to GitHub. You don't want your token in a public repo.

Q: Why use --strict-mcp-config instead of just --mcp-config?

The --strict-mcp-config flag tells Claude Code to load only the servers in that file and nothing else. Without it, Claude Code might still load globally installed MCP servers on top of your config file. The strict flag keeps it clean — only the tools this project needs.

Q: How do I know I'm ready for the next lesson?

If you've done the exercises and can tick the checklist above, you're good. Don't overthink it.

💬 Stuck? Come Talk to Us

Glossary

MCP (Model Context Protocol): The protocol that lets AI agents like Claude communicate with external tools and services. We've been using it throughout the course — Figma, Obsidian, JetBrains, and now YouTrack all connect to Claude via MCP. (first came up in Module 2, Lesson 3 - Generating the Technical Document)

.mcp.json: A project-specific configuration file that defines which MCP servers Claude Code should connect to when running in that project. Keeping this per-project (rather than global) avoids tool conflicts across multiple projects. (introduced in this lesson)

--strict-mcp-config: A Claude Code startup flag that restricts it to only loading the MCP servers defined in the specified config file — nothing else. (introduced in this lesson)

YouTrack short code: The prefix used for all issue IDs in your YouTrack project (e.g. NERT-1, NERT-2). Set when creating the project and needed when directing Claude Code to a specific project. (introduced in this lesson)

API token: A generated credential that allows external tools (like Claude Code) to authenticate with a service (like YouTrack) on your behalf. Treat it like a password — don't commit it to version control. (introduced in this lesson)