Quick Start

Table of Contents

You need a Supabase project (free tier works) and Ollama for local embeddings.

Prerequisites #

What	Where to get it
Docker	docker.com or OrbStack (Mac)
Ollama	ollama.com/download
Supabase project	supabase.com/dashboard

Docker setup #

Build #

git clone <repo-url> ogham-mcp
cd ogham-mcp
docker build -t ogham-mcp .

Set up Ollama #

ollama pull embeddinggemma       # ~600 MB download
ollama serve                     # if not already running

Create the database #

In Supabase: SQL Editor > New query > paste sql/schema.sql > Run.

Configure #

cp .env.example .env

Fill in SUPABASE_URL and SUPABASE_KEY (use the service_role key from Supabase Dashboard > Settings > API).

Verify #

docker run --rm -i --env-file .env \
  --add-host=host.docker.internal:host-gateway \
  ogham-mcp

You should see the FastMCP banner. Ctrl+C to stop.

Native setup (UV, no Docker) #

Requires Python 3.13+ and UV.

cd ogham-mcp
uv sync
uv run ogham

Follow the same Ollama, database, and .env steps as Docker setup above.

Connect your AI clients #

Each client spawns the MCP server as a subprocess. Replace /absolute/path/to/.env with the real path on your machine.

Client	Config location	Top-level key	Format
Claude Desktop (macOS)	`~/Library/Application Support/Claude/claude_desktop_config.json`	`mcpServers`	JSON
Cursor	`~/.cursor/mcp.json`	`mcpServers`	JSON
Claude Code (global)	`~/.claude.json`	`mcpServers`	JSON
Claude Code (project)	`.mcp.json`	`mcpServers`	JSON
VS Code	`.vscode/mcp.json` or user config	`servers`	JSON
Codex	`~/.codex/config.toml`	`[mcp_servers.*]`	TOML
Windsurf	`~/.windsurf/mcp.json`	`mcpServers`	JSON

Restart the client after editing config (except Claude Code and Codex, which pick up changes on next invocation).

Docker client config #

Claude Desktop / Cursor / Claude Code / Windsurf (JSON clients):

{
  "mcpServers": {
    "ogham": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--env-file", "/absolute/path/to/.env",
        "--add-host=host.docker.internal:host-gateway",
        "ogham-mcp"
      ]
    }
  }
}

VS Code (.vscode/mcp.json):

{
  "servers": {
    "ogham": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--env-file", "/absolute/path/to/.env",
        "--add-host=host.docker.internal:host-gateway",
        "ogham-mcp"
      ]
    }
  }
}

Codex (~/.codex/config.toml):

[mcp_servers.ogham]
command = "docker"
args = [
  "run", "--rm", "-i",
  "--env-file", "/absolute/path/to/.env",
  "--add-host=host.docker.internal:host-gateway",
  "ogham-mcp"
]
enabled = true

Native (UV) client config #

Claude Desktop / Cursor / Claude Code / Windsurf (JSON clients):

{
  "mcpServers": {
    "ogham": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/ogham-mcp", "ogham"]
    }
  }
}

VS Code (.vscode/mcp.json):

{
  "servers": {
    "ogham": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/ogham-mcp", "ogham"]
    }
  }
}

Codex (~/.codex/config.toml):

[mcp_servers.ogham]
command = "uv"
args = ["run", "--directory", "/absolute/path/to/ogham-mcp", "ogham"]
enabled = true

Try it out #

“Remember that our Azure resource groups use the naming convention {env}-{service}”

Then in the same client, or a different one:

“What do you know about our Azure resource naming conventions?”

It works across clients because they all hit the same Supabase database.