# Connecting to Your AI Assistant

This guide explains how to connect the MCP Context Server to Claude Code using the one-command Docker bootstrap. One command downloads the Docker Compose stack, starts all services, and fully configures Claude Code with context management hooks, skills, and rules.

## Overview

The MCP Context Server provides persistent multimodal context storage for LLM agents over the Model Context Protocol (MCP). The one-command bootstrap handles everything:

1. **Downloads and starts the Docker stack** -- PostgreSQL (with pgvector), Ollama (embedding + summary models), and the MCP Context Server (HTTP transport on port `8000`).
2. **Fully configures Claude Code** -- registers the MCP server, installs context management hooks, skills, rules, and sets appropriate permissions.

No manual steps required. No local clone of this repository needed. No Git required.

## Prerequisites

- Docker Desktop installed and running
- Windows PowerShell 5.1+ (Windows) or Bash (macOS / Linux)
- Host port `8000` available
- ~2 GB free disk space (Docker images + Ollama models)

## One-Command Setup

Run the command for your operating system. Each command does the same thing: installs `uv`, downloads the Docker Compose stack, starts the services, and fully configures Claude Code.

### Windows

```powershell
powershell -NoProfile -NoExit -ExecutionPolicy Bypass -Command "`$env:CLAUDE_CODE_TOOLBOX_ENV_CONFIG='https://raw.githubusercontent.com/alex-feel/mcp-context-server/refs/heads/main/agents/claude-code/environment-docker-ollama.yaml'; `$env:CLAUDE_CODE_TOOLBOX_SKIP_INSTALL='1'; iex (irm 'https://raw.githubusercontent.com/alex-feel/claude-code-toolbox/main/scripts/windows/setup-environment.ps1')"
```

### macOS

```bash
CLAUDE_CODE_TOOLBOX_ENV_CONFIG='https://raw.githubusercontent.com/alex-feel/mcp-context-server/refs/heads/main/agents/claude-code/environment-docker-ollama.yaml' \
CLAUDE_CODE_TOOLBOX_SKIP_INSTALL=1 \
bash -c "$(curl -fsSL https://raw.githubusercontent.com/alex-feel/claude-code-toolbox/main/scripts/macos/setup-environment.sh)"
```

### Linux

```bash
CLAUDE_CODE_TOOLBOX_ENV_CONFIG='https://raw.githubusercontent.com/alex-feel/mcp-context-server/refs/heads/main/agents/claude-code/environment-docker-ollama.yaml' \
CLAUDE_CODE_TOOLBOX_SKIP_INSTALL=1 \
bash -c "$(curl -fsSL https://raw.githubusercontent.com/alex-feel/claude-code-toolbox/main/scripts/linux/setup-environment.sh)"
```

### What This Does

Each command performs the same steps, in order:

1. Installs `uv` (always installed; required for PEP 723 hooks bundled with the environment).
2. Downloads `docker-compose.postgresql.ollama.yml` to `~/.mcp/`.
3. Runs `docker compose -f ~/.mcp/docker-compose.postgresql.ollama.yml up -d`. This starts:
   - `mcp-context-server` (HTTP transport on port `8000`)
   - `postgres` (with the pgvector extension for semantic search)
   - `ollama` (stock `ollama/ollama:latest` image; pulls `qwen3-embedding:0.6b` and `qwen3:0.6b` on first run)
4. Configures Claude Code to connect to the server via HTTP at `http://localhost:8000/mcp`.
5. Installs the bundled context-server skills, hooks, and rules into `~/.claude/`.

`CLAUDE_CODE_TOOLBOX_SKIP_INSTALL=1` tells the bootstrap to skip Claude Code itself and its IDE extensions if you already have them installed -- `uv` and the environment configuration are still applied.

**First-run note.** Ollama pulls roughly 1.2 GB of model data (`qwen3-embedding:0.6b` + `qwen3:0.6b`) on the first start. Allow 2-5 minutes before the server is ready to serve embedding-backed tools. To follow progress:

```bash
docker compose -f ~/.mcp/docker-compose.postgresql.ollama.yml logs -f ollama
```

To verify the server responds:

```bash
curl http://localhost:8000/health
```

## Ollama + OpenAI Summary Variant

This variant uses **Ollama for embeddings** and **OpenAI for summary generation**. The embedding model (`qwen3-embedding:0.6b`) runs locally via Ollama, while summaries are generated by OpenAI (`gpt-5.4-nano`), producing higher-quality context summaries at the cost of an API key requirement.

### Additional Prerequisites

- An OpenAI API key (see [How to Get an OpenAI API Key](#how-to-get-an-openai-api-key) below)

### Step 1: Create the `.env` File

The Docker Compose stack reads the OpenAI API key from a `.env` file in the `~/.mcp/` directory. Create this file **before** running the setup command.

**Windows PowerShell:**

```powershell
New-Item -ItemType Directory -Force -Path "$HOME\.mcp" | Out-Null
Set-Content -Path "$HOME\.mcp\.env" -Value "OPENAI_API_KEY=sk-your-key-here"
```

**macOS / Linux:**

```bash
mkdir -p ~/.mcp && echo 'OPENAI_API_KEY=sk-your-key-here' > ~/.mcp/.env
```

Replace `sk-your-key-here` with your actual OpenAI API key.

### Step 2: Run the One-Command Setup

#### Windows

```powershell
powershell -NoProfile -NoExit -ExecutionPolicy Bypass -Command "`$env:CLAUDE_CODE_TOOLBOX_ENV_CONFIG='https://raw.githubusercontent.com/alex-feel/mcp-context-server/refs/heads/main/agents/claude-code/environment-docker-ollama-openai.yaml'; `$env:CLAUDE_CODE_TOOLBOX_SKIP_INSTALL='1'; iex (irm 'https://raw.githubusercontent.com/alex-feel/claude-code-toolbox/main/scripts/windows/setup-environment.ps1')"
```

#### macOS

```bash
CLAUDE_CODE_TOOLBOX_ENV_CONFIG='https://raw.githubusercontent.com/alex-feel/mcp-context-server/refs/heads/main/agents/claude-code/environment-docker-ollama-openai.yaml' \
CLAUDE_CODE_TOOLBOX_SKIP_INSTALL=1 \
bash -c "$(curl -fsSL https://raw.githubusercontent.com/alex-feel/claude-code-toolbox/main/scripts/macos/setup-environment.sh)"
```

#### Linux

```bash
CLAUDE_CODE_TOOLBOX_ENV_CONFIG='https://raw.githubusercontent.com/alex-feel/mcp-context-server/refs/heads/main/agents/claude-code/environment-docker-ollama-openai.yaml' \
CLAUDE_CODE_TOOLBOX_SKIP_INSTALL=1 \
bash -c "$(curl -fsSL https://raw.githubusercontent.com/alex-feel/claude-code-toolbox/main/scripts/linux/setup-environment.sh)"
```

### What This Does

The setup performs the same steps as the default variant (see [One-Command Setup](#one-command-setup) above), with these differences:

1. Downloads `docker-compose.postgresql.ollama-openai.yml` to `~/.mcp/` (instead of the default Ollama-only compose file).
2. Uses the `latest-ollama-openai` Docker image, which includes the OpenAI Python SDK for summary generation.
3. Ollama pulls only the embedding model (`qwen3-embedding:0.6b`, ~0.6 GB). The summary model is not downloaded because summaries are generated by the OpenAI API.
4. Reads `OPENAI_API_KEY` from `~/.mcp/.env` and passes it to the container for summary generation.

**First-run note.** Ollama pulls roughly 0.6 GB of model data (`qwen3-embedding:0.6b`) on the first start. Allow 1-3 minutes before the server is ready. To follow progress:

```bash
docker compose -f ~/.mcp/docker-compose.postgresql.ollama-openai.yml logs -f ollama
```

To verify the server responds:

```bash
curl http://localhost:8000/health
```

### Comparison with Default Setup

| Feature              | Default (Ollama)                       | Ollama + OpenAI                               |
|----------------------|----------------------------------------|-----------------------------------------------|
| Embedding provider   | Ollama (`qwen3-embedding:0.6b`)        | Ollama (`qwen3-embedding:0.6b`)               |
| Summary provider     | Ollama (`qwen3:0.6b`)                  | OpenAI (`gpt-5.4-nano`)                       |
| Ollama models pulled | 2 (~1.2 GB)                            | 1 (~0.6 GB)                                   |
| First-run time       | 2-5 minutes                            | 1-3 minutes                                   |
| OpenAI API key       | Not required                           | Required                                      |
| `.env` file          | Optional                               | Required (`~/.mcp/.env`)                      |
| Docker image tag     | `latest`                               | `latest-ollama-openai`                        |
| Compose file         | `docker-compose.postgresql.ollama.yml` | `docker-compose.postgresql.ollama-openai.yml` |

### Why the API Key Cannot Be Passed from the Command Line

The `docker-compose.postgresql.ollama-openai.yml` file loads `OPENAI_API_KEY` from a `.env` file via the `env_file` directive -- it does not use `${OPENAI_API_KEY}` interpolation in the `environment:` section. Because `env_file` reads exclusively from a file on disk, setting `export OPENAI_API_KEY=sk-...` in the shell before running `docker compose up` has no effect on the container environment. The `.env` file is the only supported mechanism.

### How to Get an OpenAI API Key

1. Go to [platform.openai.com](https://platform.openai.com/) and sign up (or sign in with an existing account). You can register with an email address or use a Google, Microsoft, or Apple account.
2. Navigate to **Settings > Billing** ([platform.openai.com/account/billing/overview](https://platform.openai.com/account/billing/overview)) and add a payment method. OpenAI uses a prepaid credit system -- you add funds and API calls deduct from that balance. The minimum top-up is $5.
3. Go to **API Keys** ([platform.openai.com/api-keys](https://platform.openai.com/api-keys)) and click **Create new secret key**. Give the key a descriptive name (e.g., "MCP Context Server") and copy it immediately -- OpenAI displays the key only once.

Use the copied key in the `.env` file in [Step 1](#step-1-create-the-env-file) above.

For full details, see the [OpenAI Developer Quickstart](https://developers.openai.com/docs/quickstart).

### Cost Estimate

At current [OpenAI API pricing](https://openai.com/api/pricing/), `gpt-5.4-nano` costs $0.20 per 1 million input tokens and $1.25 per 1 million output tokens. In practice, generating 1,000 summaries costs approximately **$1 USD** depending on the average length of stored context entries.

## Troubleshooting

| Symptom                                                                                   | Cause                                                                     | Fix                                                                                                                                                                                           |
|-------------------------------------------------------------------------------------------|---------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `docker: command not found` (Windows) or Docker Desktop is not running                    | Docker Desktop is not installed or not started                            | Install [Docker Desktop](https://www.docker.com/products/docker-desktop/) and make sure it is running before re-running the bootstrap                                                         |
| `Error response from daemon: ... bind for 0.0.0.0:8000 failed: port is already allocated` | Another process is using port `8000` on the host                          | Stop the conflicting process, OR edit `~/.mcp/docker-compose.postgresql.ollama.yml` and remap the host port (e.g., `"8001:8000"`), then update your client URL to `http://localhost:8001/mcp` |
| Bootstrap reports "Ollama not healthy yet" / `/health` returns connection refused         | First-run model download still in progress                                | Watch progress with `docker compose -f ~/.mcp/docker-compose.postgresql.ollama.yml logs -f ollama`. Wait until both `qwen3-embedding:0.6b` and `qwen3:0.6b` are pulled                        |
| GPU acceleration is not used                                                              | Docker Compose file's GPU section is commented out by default             | See the [GPU Acceleration Guide](deployment/gpu-acceleration.md) for vendor-specific instructions (NVIDIA / AMD ROCm / Intel Vulkan)                                                          |
| Two compose variants conflict over the `ollama-models` volume                             | The `ollama-models` named volume is shared by all Ollama compose variants | Only one Ollama compose variant can run at a time. Stop the other variant before starting a new one: `docker compose -f <other-file> down`                                                    |
| `validating .../docker-compose.postgresql.ollama-openai.yml: ... .env: not found`         | The `.env` file is missing from `~/.mcp/`                                 | Create the file before starting the stack -- see [Step 1: Create the `.env` File](#step-1-create-the-env-file) above                                                                          |
| `openai.AuthenticationError: Incorrect API key provided` or summaries are empty           | The OpenAI API key in `~/.mcp/.env` is invalid or expired                 | Open `~/.mcp/.env`, verify the key starts with `sk-`, and confirm it is active at [platform.openai.com/api-keys](https://platform.openai.com/api-keys). Replace the key and restart the stack |

## Update and Uninstall

**Update** -- exit Claude Code and re-run the one-command bootstrap for your OS (see [One-Command Setup](#one-command-setup) above). This re-downloads the Compose file and restarts the stack with the latest images.

**Stop the stack (preserve data):**

```bash
docker compose -f ~/.mcp/docker-compose.postgresql.ollama.yml down
```

**Remove the stack and all data (Docker volumes):**

```bash
docker compose -f ~/.mcp/docker-compose.postgresql.ollama.yml down -v
```

This deletes the PostgreSQL data, the SQLite/Postgres backend volume, and the `ollama-models` volume (forcing re-download of models on the next start).

For the Ollama + OpenAI variant, substitute the compose file name in the commands above:

```bash
# Stop (preserve data)
docker compose -f ~/.mcp/docker-compose.postgresql.ollama-openai.yml down

# Remove stack and all data
docker compose -f ~/.mcp/docker-compose.postgresql.ollama-openai.yml down -v
```

**Remove the downloaded Compose file:**

```powershell
# Windows PowerShell
Remove-Item -Recurse -Force "$env:USERPROFILE\.mcp"
```

```bash
# macOS / Linux
rm -rf ~/.mcp
```

**Unregister the server from Claude Code:**

```bash
claude mcp remove context-server
```

## Related Documentation

- [Docker Deployment Guide](deployment/docker.md) -- full reference for all 15 Docker Compose configurations, environment variables, advanced configuration, and PostgreSQL backend error scenarios.
- [GPU Acceleration Guide](deployment/gpu-acceleration.md) -- NVIDIA, AMD ROCm, and Intel/Vulkan GPU configuration.
- [Database Backends Guide](database-backends.md) -- choosing between SQLite and PostgreSQL.
- [Authentication Guide](authentication.md) -- bearer-token authentication for HTTP transport.
- [Environment Variables Reference](environment-variables.md) -- full reference for every environment variable the server understands.
- [README](../README.md) -- feature overview and entry point.
