MCP server in JetBrains AI Assistant

Configuring MCP servers in JetBrains settings

JetBrains AI Assistant supports two configuration paths: the IDE settings UI for quick setup, and a mcp.json file for project-level (team-sharable) configuration.

Via IDE settings (user-level):

1. Open Settings (Ctrl+Alt+S / Cmd+,)
2. Navigate to Tools → AI Assistant → Model Context Protocol (MCP)
3. Click + to add a new server
4. Enter the server name, select the transport type (HTTP or stdio), and fill in the URL or command
5. Click OK and wait for the status indicator to show "Connected"

Settings configured via the UI are stored in JetBrains' user-level configuration directory — they apply across all projects but are not shared with teammates.

Via mcp.json (project-level):

Create .idea/mcp.json or mcp.json at the project root. JetBrains detects either location at project open time:

// mcp.json — project root (committed to git)
{
  "servers": {
    "project-api-tools": {
      "url": "https://mcp.myproject.example.com/mcp",
      "headers": {
        "X-API-Key": "${MCP_API_KEY}"
      }
    },
    "code-search": {
      "command": "node",
      "args": ["/path/to/search-mcp/dist/index.js", "--index", "."],
      "env": {
        "NODE_ENV": "production"
      }
    },
    "python-analysis": {
      "command": "/usr/bin/python3",
      "args": ["-m", "myproject.mcp_server"],
      "env": {
        "PYTHONPATH": "${PROJECT_ROOT}/src"
      }
    }
  }
}

JetBrains supports environment variable interpolation in the mcp.json file using ${VAR_NAME} syntax — variables are resolved from the IDE process environment. For macOS, where the IDE environment may not include shell-defined variables, use the env key to explicitly set required variables.

HTTP transport: requirements and CORS

For HTTP MCP servers, JetBrains makes requests from the IDE process (not a browser). This has two implications:

1. No browser CORS restrictions apply. JetBrains makes HTTP requests directly via Java's HttpClient — there is no browser origin enforcement. Your server does not need CORS headers specifically for JetBrains. (Configure CORS if you also serve browser clients.)
2. SSL certificate validation is strict. JetBrains uses the Java trust store. Self-signed certificates on localhost work only if the certificate is added to the JetBrains system trust store or the IDE's proxy settings are configured to bypass certificate checks for localhost. For development, use HTTP (not HTTPS) on localhost to avoid certificate issues.

Authentication headers set in mcp.json (or the settings UI) are included on every MCP request. JetBrains does not prompt the developer for credentials at connection time — if your header value contains ${VAR_NAME} and the variable is not set, the literal string ${MCP_API_KEY} is sent as the header value, causing an authentication failure with no visible error in the IDE.

Verify that environment variable interpolation is working before deploying mcp.json to your team. Add a sentinel tool to your MCP server that returns whether the server received the correct authentication header — this makes misconfigured credentials immediately visible in the AI chat panel rather than silently failing.

Stdio transport: environment and path gotchas

Stdio MCP servers are launched by JetBrains as subprocesses. The subprocess environment is critical and differs by platform:

The most common failure mode: node, python3, or npx is installed via nvm, pyenv, or brew into a PATH that only exists in the shell session. JetBrains' GUI-launched subprocess cannot find the binary and the stdio server fails to start silently.

Solutions:

// Option 1: Absolute path to binary — most reliable
{
  "servers": {
    "my-server": {
      "command": "/Users/dev/.nvm/versions/node/v22.0.0/bin/node",
      "args": ["dist/index.js"]
    }
  }
}

// Option 2: Wrapper shell script that sets environment
{
  "servers": {
    "my-server": {
      "command": "/bin/bash",
      "args": ["-c", "source ~/.zshrc && node /path/to/dist/index.js"],
      "env": {
        "HOME": "/Users/dev"  // Required for source to work correctly
      }
    }
  }
}

// Option 3: Explicit env block to replicate shell-defined variables
{
  "servers": {
    "my-server": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "PATH": "/Users/dev/.nvm/versions/node/v22.0.0/bin:/usr/local/bin:/usr/bin:/bin",
        "NVM_DIR": "/Users/dev/.nvm"
      }
    }
  }
}

Tool invocation in the AI Assistant panel

Open the AI Assistant with the chat icon in the right tool window bar, or use the keyboard shortcut (configurable in Settings → Keymap → AI Assistant). Tools from connected MCP servers appear in the AI Assistant's context — when you ask a question that the LLM determines requires a tool, it proposes a tool call.

JetBrains AI Assistant shows tool call proposals inline in the chat with:

• The tool name and description
• The arguments the LLM intends to pass (formatted as a key-value list)
• Run and Skip buttons

Unlike VS Code (which has both "run once" and "always allow" options), JetBrains AI Assistant in most versions requires explicit approval for each tool call — there is no persistent "always allow" permission for MCP tools. This is intentional: JetBrains prioritizes developer control over tool invocation convenience.

JetBrains AI Assistant supports multiple AI providers — JetBrains AI Service (the default), Anthropic, OpenAI, and others configurable in Settings → Tools → AI Assistant → AI Provider. MCP tool calling works with providers that support tool schemas in their API (Claude models, GPT-4o family). If you configure a provider without tool calling support, MCP tools are registered but never invoked — the chat proceeds without tool calls and no error is shown.

Per-IDE behavioral differences

JetBrains IDEs share the AI Assistant plugin but differ in their project-type context, which affects which MCP tools the LLM is most likely to invoke:

The AI Assistant plugin version is the same across all JetBrains IDEs — MCP support is a plugin-level feature, not an IDE-level one. If you test your MCP server with IntelliJ IDEA and it works, it will work identically in WebStorm and PyCharm on the same JetBrains platform version.

Debugging MCP connections in JetBrains

Access the AI Assistant diagnostic log from Help → Show Log in Finder / Explorer (the main IDE log) and look for MCP-tagged entries. On macOS, the log file is at ~/Library/Logs/JetBrains/<IDE><version>/idea.log.

For more verbose MCP logging, enable AI Assistant debug logging in Help → Diagnostic Tools → Debug Log Settings and add:

#com.intellij.ml.llm.mcp:debug

After adding this debug pattern, restart the IDE and trigger a MCP connection — the log will show the full JSON-RPC exchange:

2026-06-26 14:23:01,123 [  123]   DEBUG - .intellij.ml.llm.mcp.client - Connecting to MCP server: project-api-tools
2026-06-26 14:23:01,234 [  234]   DEBUG - .intellij.ml.llm.mcp.client - → {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","clientInfo":{"name":"IntelliJ IDEA","version":"2025.1.2"}}}
2026-06-26 14:23:01,456 [  456]   DEBUG - .intellij.ml.llm.mcp.client - ← {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","serverInfo":{"name":"project-tools","version":"1.0.0"},"capabilities":{"tools":{}}}}
2026-06-26 14:23:01,567 [  567]   DEBUG - .intellij.ml.llm.mcp.client - → {"jsonrpc":"2.0","id":2,"method":"tools/list"}
2026-06-26 14:23:01,678 [  678]   DEBUG - .intellij.ml.llm.mcp.client - ← {"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"list_endpoints","description":"List all API endpoints","inputSchema":{...}}]}}
2026-06-26 14:23:01,679 [  679]   INFO  - .intellij.ml.llm.mcp.client - MCP server "project-api-tools" connected: 1 tool(s)

Common failure patterns in JetBrains MCP logs:

Monitoring MCP servers used in JetBrains workflows

JetBrains AI Assistant connects to MCP servers at IDE startup (when a project with mcp.json opens) and when you open a new project. If the MCP server is unreachable at startup, JetBrains logs an error and continues — the AI Assistant works without MCP tools rather than failing to open. This silent degradation means developers may not notice an outage until they specifically try to use a tool.

The JetBrains-specific monitoring challenge: JetBrains reconnects to MCP servers only at IDE restart or explicit reconnect via the settings UI. A server that goes down while the IDE is open is not retried until the developer manually reconnects or restarts IntelliJ. This means a server that goes down at 9:00 AM may not be noticed by the developer until 4:00 PM when they restart IntelliJ for a different reason.

AliveMCP probes your server every 60 seconds regardless of client reconnect behavior, giving you accurate availability data independent of JetBrains' reconnect cadence. When you commit mcp.json to a project repository, every developer who opens the project depends on your server — add AliveMCP monitoring as part of your server's deployment checklist.

Further reading

• MCP server in VS Code — .vscode/mcp.json configuration and debugging
• MCP server in Zed editor — context_servers configuration
• MCP server in Cursor — configuring MCP for AI-assisted development
• MCP stdio transport — subprocess environment and lifecycle
• MCP tool design — writing descriptions that LLMs select correctly
• AliveMCP — continuous protocol monitoring for MCP servers