> ## Documentation Index
> Fetch the complete documentation index at: https://docs.codealive.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Zed

> Connect CodeAlive with the Zed Agent using remote MCP

## Overview

Zed supports remote MCP servers directly. Connect the Zed Agent to CodeAlive over HTTP to search indexed repositories and retrieve code context without running a local MCP process.

<Info>
  Older CodeAlive instructions used Docker because Zed previously supported only local STDIO servers. Current Zed releases support remote servers with a URL and custom HTTP headers.
</Info>

## Prerequisites

* A current version of [Zed](https://zed.dev/download)
* A CodeAlive account and [API key](https://app.codealive.ai/settings/api-keys)
* At least one indexed repository or workspace in CodeAlive
* An LLM configured for the Zed Agent

## Remote MCP Setup

<Steps>
  <Step title="Open MCP settings">
    Open **Settings → AI → MCP Servers**, click **Add Server**, and choose **Add Remote Server**.

    You can also run `agent: open settings`, select **MCP Servers**, or run `zed: open settings file` to edit the JSON directly.
  </Step>

  <Step title="Add CodeAlive">
    Add CodeAlive under `context_servers` in your user `settings.json`:

    ```json theme={null}
    {
      "context_servers": {
        "codealive": {
          "url": "https://mcp.codealive.ai/api",
          "headers": {
            "Authorization": "Bearer YOUR_API_KEY_HERE"
          }
        }
      }
    }
    ```

    Replace `YOUR_API_KEY_HERE` with your CodeAlive API key. Zed's remote MCP format does not require a `type` field.
  </Step>

  <Step title="Verify the connection">
    Return to **Settings → AI → MCP Servers** and find `codealive`. A green indicator with the tooltip **Server is active** confirms that Zed loaded the server and discovered its tools.
  </Step>
</Steps>

<Warning>
  Zed stores custom remote MCP headers in `settings.json`. Use the user settings file and do not commit an API key in project-level `.zed/settings.json`.
</Warning>

## Docker Alternative

If direct remote HTTP access is unavailable on your network, run CodeAlive through Docker using Zed's local MCP format:

```json theme={null}
{
  "context_servers": {
    "codealive": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "CODEALIVE_API_KEY=YOUR_API_KEY_HERE",
        "ghcr.io/codealive-ai/codealive-mcp:main"
      ],
      "env": {}
    }
  }
}
```

Docker must be installed and running before Zed starts this server.

## Tool Permissions

Zed asks for confirmation before tool calls by default. Review each CodeAlive tool call before approving it. If you customize Zed's permissions, MCP tool keys use this format:

```text theme={null}
mcp:codealive:<tool_name>
```

For example, `mcp:codealive:semantic_search` identifies the CodeAlive semantic search tool.

## Try It

Ask the Zed Agent:

* "Use CodeAlive to show me all available repositories"
* "Use CodeAlive semantic search to find the authentication flow"
* "Find callers of this service and fetch the relevant implementations"

Mentioning CodeAlive by name helps the model select its MCP tools. For consistent routing, add instructions telling the agent to prefer `semantic_search` and `grep_search` for indexed-code exploration.

## Troubleshooting

<AccordionGroup>
  <Accordion title="The server is not active">
    1. Check that `codealive` is inside the top-level `context_servers` object
    2. Confirm that the URL is `https://mcp.codealive.ai/api`
    3. Validate the JSON syntax and reopen **Settings → AI → MCP Servers**
    4. Update Zed if **Add Remote Server** is not available
  </Accordion>

  <Accordion title="Authentication fails">
    1. Confirm that the API key is active in the [CodeAlive dashboard](https://app.codealive.ai/settings/api-keys)
    2. Ensure the `Authorization` value begins with `Bearer `
    3. Check that the API key contains no surrounding spaces or copied quotation marks
  </Accordion>

  <Accordion title="The agent does not call CodeAlive tools">
    1. Confirm that the server indicator is green
    2. Mention CodeAlive explicitly in the prompt
    3. Check that tool permissions do not deny `mcp:codealive:*`
    4. Add CodeAlive routing guidance to your project or global agent instructions
  </Accordion>
</AccordionGroup>

## Related Resources

* [Zed MCP documentation](https://zed.dev/docs/ai/mcp)
* [MCP Overview](/integrations/mcp)
* [Instructing Coding Agents](/guides/instructing-agents)
* [Self-Hosting Guide](/integrations/mcp/self-hosting)