# How to Integrate Goose with JetBrains or Zed Using ACP: Complete Setup Guide

> Easily integrate Goose with JetBrains IDEs and Zed using ACP. Follow this complete setup guide to configure your ACP server and agent for seamless workflow.

- Repository: [Block Open Source/goose](https://github.com/block/goose)
- Tags: how-to-guide
- Published: 2026-04-05

---

**You can integrate Goose with JetBrains IDEs and Zed by exposing JetBrains as an MCP server, registering it as a Goose extension via `goose configure add`, then configuring Zed to launch `goose acp` as an agent server in its [`settings.json`](https://github.com/block/goose/blob/main/settings.json).**

The `block/goose` repository implements the **Agent Client Protocol (ACP)**, a JSON-RPC-over-stdio standard that allows editors to act as clients of an AI-agent server. This guide demonstrates how to integrate Goose with JetBrains IDEs and the Zed editor using ACP, enabling you to leverage JetBrains' refactoring engines and code analysis tools directly from Zed's chat interface.

## Understanding the ACP-MCP Bridge Architecture

Goose serves as the central bridge between JetBrains' MCP implementation and Zed's ACP client. The data flow works as follows:

1. **JetBrains IDE** runs an MCP server locally (available via HTTP stream or STDIO)
2. **Goose** loads this MCP server as an extension in `crates/goose/src/extensions/`
3. **Zed** connects to Goose via ACP (`goose acp` as implemented in `crates/goose-acp/`)
4. All MCP tools exposed by JetBrains become available as Goose tools inside Zed

According to the source code in [`documentation/docs/guides/acp-clients.md`](https://github.com/block/goose/blob/main/documentation/docs/guides/acp-clients.md), this architecture allows Zed to access IDE-specific capabilities—such as JetBrains' code indexes and refactoring engines—without native JetBrains plugin support.

## Step 1: Configure the JetBrains MCP Extension in Goose

JetBrains IDEs expose MCP servers in two formats depending on the version: **Streamable HTTP** (2026.1+) or **STDIO** (2025.2–2025.x). Choose the method matching your IDE version.

### For JetBrains 2026.1+ (Streamable HTTP)

First, enable the MCP server in your JetBrains IDE:

1. Open **Settings → Tools → MCP Server**
2. Enable *MCP Server* and click **Copy HTTP Stream Config** to get a URL like `http://127.0.0.1:64344/stream`
3. Register this endpoint with Goose:

**Using Goose Desktop:**

```text
Extension Name: JetBrains
Type: Streamable HTTP
Description: Integrate goose with any JetBrains IDE
URL: http://127.0.0.1:64344/stream

```

**Using Goose CLI:**

```bash
goose configure add \
  --name jetbrains \
  --type http \
  --description "Integrate goose with any JetBrains IDE" \
  --url http://127.0.0.1:64344/stream \
  --timeout 300

```

### For JetBrains 2025.2–2025.x (STDIO)

For older versions using STDIO transport:

1. Open **Settings → Tools → MCP Server**, enable it, and click **Copy Stdio Config**
2. Extract the `command`, `args`, and `env` values from the configuration
3. Add the extension with environment variables:

**Using Goose Desktop:**

```text
Extension Name: JetBrains
Type: STDIO
Description: Integrate goose with any JetBrains IDE
Command: <command> <args>
Environment Variables: IJ_MCP_SERVER_PORT=<port-from-env>

```

**Using Goose CLI:**

```bash
goose configure add \
  --name jetbrains \
  --type stdio \
  --description "Integrate goose with any JetBrains IDE" \
  --command "YOUR_COMMAND_AND_ARGS_FROM_IDE" \
  --env IJ_MCP_SERVER_PORT=YOUR_PORT \
  --timeout 300

```

Reference implementation details are documented in [`documentation/docs/mcp/jetbrains-mcp.md`](https://github.com/block/goose/blob/main/documentation/docs/mcp/jetbrains-mcp.md).

## Step 2: Connect Zed to Goose via ACP

Once the JetBrains extension is registered in Goose, configure Zed to use Goose as an agent server.

1. **Install the Goose CLI** and verify with `goose --version`
2. **Open Zed's settings** (`Cmd ⌥ ,` on macOS or `Ctrl Alt ,` on Linux/Windows)
3. **Add the Goose agent server** to [`settings.json`](https://github.com/block/goose/blob/main/settings.json):

```json
{
  "agent_servers": {
    "goose": {
      "command": "goose",
      "args": ["acp"],
      "env": {}
    }
  }
}

```

The `goose acp` command (entry point in [`crates/goose-cli/src/main.rs`](https://github.com/block/goose/blob/main/crates/goose-cli/src/main.rs)) launches the ACP server implemented in `crates/goose-acp/`, which handles the JSON-RPC communication with Zed.

### Optional: Configure Multiple Model Instances

You can run multiple Goose instances with different models by adding entries with distinct environment variables:

```json
{
  "agent_servers": {
    "goose": {
      "command": "goose",
      "args": ["acp"],
      "env": {}
    },
    "goose (GPT-4o)": {
      "command": "goose",
      "args": ["acp"],
      "env": {
        "GOOSE_PROVIDER": "openai",
        "GOOSE_MODEL": "gpt-4o"
      }
    }
  }
}

```

4. **Launch an ACP session**: Open the Agent panel (sparkles icon) in Zed, create a new thread, and select **goose**.

## Step 3: Using JetBrains Tools from Within Zed

Once connected, all tools exposed by the JetBrains MCP server are automatically available in Zed's chat interface. The extension loading logic in `crates/goose/src/extensions/` dynamically registers these capabilities with the ACP server.

**Example workflow:**

Ask Goose: *"Refactor this Java file using JetBrains code-analysis tools."*

Goose forwards the request to the JetBrains MCP server, which leverages the IDE's internal indexes and refactoring engine. The updated code returns through Goose to Zed's chat window.

To discover available tools, type `help` or ask *"what tools are loaded?"* during an active ACP session.

## Summary

- **Expose JetBrains as MCP**: Configure the MCP server in JetBrains settings (HTTP for 2026.1+, STDIO for 2025.x)
- **Register with Goose**: Use `goose configure add` with `--type http` or `--type stdio` depending on your transport method
- **Connect Zed**: Add `goose acp` as an `agent_server` in Zed's [`settings.json`](https://github.com/block/goose/blob/main/settings.json)
- **Access tools**: All JetBrains refactoring and navigation tools become available in Zed's chat interface through the ACP bridge

## Frequently Asked Questions

### What is the difference between MCP and ACP in this setup?

**MCP (Model Context Protocol)** is the protocol JetBrains uses to expose IDE capabilities, while **ACP (Agent Client Protocol)** is Goose's JSON-RPC-over-stdio standard for editor communication. Goose acts as a bridge, translating between the JetBrains MCP server and Zed's ACP client, allowing the two different protocols to interoperate.

### Can I use multiple Goose instances with different models in Zed?

Yes. Add multiple entries to the `agent_servers` object in Zed's [`settings.json`](https://github.com/block/goose/blob/main/settings.json), each with unique keys (e.g., `"goose"` and `"goose (GPT-4o)"`). Set environment variables like `GOOSE_PROVIDER` and `GOOSE_MODEL` to configure different models for each instance, enabling you to switch between cost-effective and high-capability models within the same editor session.

### Why does my JetBrains MCP connection timeout?

Timeout issues typically occur when the `IJ_MCP_SERVER_PORT` environment variable is misconfigured for STDIO connections or when the HTTP stream URL is incorrect for newer JetBrains versions. Verify that the port matches the value shown in **Settings → Tools → MCP Server**, and ensure the `--timeout` parameter in `goose configure add` is set sufficiently high (300 seconds recommended for long-running refactoring operations).

### Is this supported on all JetBrains IDEs?

Yes. The MCP server implementation is available across the JetBrains ecosystem, including IntelliJ IDEA, PyCharm, GoLand, WebStorm, and other IDEs based on the IntelliJ platform. The configuration process remains identical regardless of the specific JetBrains product, as documented in [`documentation/docs/mcp/jetbrains-mcp.md`](https://github.com/block/goose/blob/main/documentation/docs/mcp/jetbrains-mcp.md).