← Back to the plugin
Gateway Plugin · Quick Setup

Connect the plugin to your gateway

Your containers are running — nice work. Now the PyCharm IDEAgent plugin just needs to know where to find them. This is a short, five-minute setup you do once. Follow the steps in order, top to bottom. Each one is a single screen in the plugin's Settings.

Before you start

First, install the plugin from the JetBrains Marketplace — it's available directly inside PyCharm / IntelliJ, or via the button below.

This guide picks up after the gateway containers are already up and running. You just need two things handy:

  • The address of the machine running the containers. If Docker runs on the same computer as PyCharm, that address is localhost. If Docker runs on a different machine (like a server in another room), it's that machine's real IP address — for example 192.168.158.59.
  • An API key for the model provider you want to use (OpenAI, Anthropic or Google) — or the address of your own Ollama if you want to run fully offline.

Now open PyCharm, go to Settings → Tools → IDEAgent, and follow along.

Step 1 — Tell the plugin where the gateway is

On the main IDEAgent settings screen there is a Gateway URL box. Type in the address of the machine running your containers, followed by the gateway port.

  • Docker on the same computer as PyCharm → use http://localhost:8765
  • Docker on a remote server → use that server's IP, e.g. http://192.168.158.59:8765

Then press Test connection. If it turns green, the plugin can see your gateway and you're good to move on. If it doesn't, double-check the IP and that the containers are running.

IDEAgent main settings with the Gateway URL box and Test connection button
Main settings. Put your gateway address in the Gateway URL box (server IP + port, or localhost if it runs on this machine), then press Test connection.

Step 2 — Add the default MCP server

The MCP server is where the agent gets its tools — searching your code, remembering your project, and more. Go to MCP Servers, press Add, and paste in the block below. Change <Local Container IP> to the same address you used in Step 1 (localhost, or your server's IP).

{ "mcpServers": { "mcp-server": { "url": "http://<Local Container IP>:5820/mcp", "type": "http" } } }

After you add it, make sure it shows a green dot (connected). You can press Refresh status to check. The docs-langchain and reference-langchain servers you may see there are optional extras — the one you must have is mcp-server.

MCP Servers settings page showing mcp-server connected on port 5820
MCP Servers. Add mcp-server with the block above, then check for the green “connected” dot. Note the MCP port is 5820 — different from the gateway port in Step 1.

Step 3 — Add your provider keys (or your Ollama address)

Open Models & API keys. Here you tell the plugin which brain to use:

  • Using a cloud provider? Paste your Anthropic, OpenAI and/or Google API key into the matching box. You only need the ones you plan to use.
  • Running fully offline with Ollama? Leave the cloud keys blank and put your Ollama address in the Ollama base URL box — for example http://192.168.158.59:11434.

Your keys are stored safely in your computer's own keychain — never in a plain text file. Leave a box blank to let the gateway fall back to its own setting for that provider.

Models and API keys settings with Anthropic, OpenAI, Google key fields and the Ollama base URL
Models & API keys. Fill in the key(s) for the provider you want, or set the Ollama base URL to stay fully local. Any provider you give a key to shows up in the model picker.

Step 4 — Restart PyCharm, then pick your dedicated models

Close and reopen PyCharm so all your settings load fresh. When it's back, open Dedicated Models. These are two small helper models that keep things tidy:

  • Title Model — writes a short name for each chat automatically. This same model is also used for summarizing data in the gateway.
  • RAG Model — used when the agent searches your project. If you set up Ollama, you can pick the small local model your RAG will use here.

A small, fast model is plenty for both of these.

Dedicated models settings with a Title Model and a RAG Model chosen
Dedicated models. Turn on Auto-Titles and pick a small Title model, then choose your RAG model. With Ollama, pick the local model your RAG should use.
That's it — the plugin is set up. Open a new thread and say hello to the agent. Everything below this line is optional and only if you want it.

The RAG File Watcher

The RAG File Watcher keeps your project search index up to date as you edit, so the agent always sees the latest version of your code. It's a separate plugin you install from the JetBrains Marketplace (search for it by name inside PyCharm's plugin settings). Once installed, point it at your RAG server and let it index your project. You can skip this at first and add it later.

Optional — talk and listen: Whisper & Piper

Want to speak to the agent and have it read replies aloud? That uses two free, fully local tools: Whisper for speech-to-text (listening to you) and Piper for text-to-speech (talking back). Nothing you say leaves your computer. Install them on the machine where PyCharm runs, then the plugin can detect them.

On a Mac

The easiest way is with Homebrew. Open the Terminal app and run:

# Whisper (speech-to-text) brew install whisper-cpp # Piper (text-to-speech) pip3 install piper-tts

On Linux

Open a terminal. For most distributions (Ubuntu / Debian):

# Make sure Python's package installer is available sudo apt update && sudo apt install -y python3-pip # Whisper (speech-to-text) pip3 install openai-whisper # Piper (text-to-speech) pip3 install piper-tts

On other distributions use your own package manager (for example dnf on Fedora) to install python3-pip first, then the same two pip3 commands.

On Windows

First install Python and tick “Add Python to PATH” during setup. Then open PowerShell and run:

# Whisper (speech-to-text) pip install openai-whisper # Piper (text-to-speech) pip install piper-tts

Turn them on in the plugin

  1. Open the Speech-to-text settings and switch it on. Press Detect so the plugin finds Whisper, then pick a model to download.
  2. Open the Text-to-speech settings and switch it on. Press Detect to find Piper, then download a voice.

Now you can dictate to the agent and hear its answers — all on your own machine, with no cloud voice service involved.

See all plugin settings →