# Installing rosetta-mcp-server

Per-platform install walkthroughs for the
[rosetta-mcp-server](README.md) MCP gateway binary.

The binary is a single self-contained executable — the OpenAPI spec
and composites catalog are baked in via `go:embed`. No runtime data
files, no language runtimes, no DB connections. Pick your platform
below.

## Before you start

You will need:

1. **A bearer token (`ROSETTA_API_KEY`).** Register at
   [https://rosetta-design.com](https://rosetta-design.com), log
   in, and generate an API key in **Settings → API Keys**. The
   token shape is `rsk_<32+ alphanumeric>`. Without this, the
   binary refuses to start.
2. **A terminal.** macOS / Linux: run commands in **Terminal** (or
   the integrated terminal in VS Code). Windows: run commands in
   **PowerShell** (not `cmd.exe`).

## Version cheatsheet

From v0.1.2 onwards, the release archive filenames embed the
**release version** (the same `X.Y.Z` as the URL tag, minus the
`v`):

```
URL pattern:  https://github.com/vernonkeenan/rosetta-mcp-server/releases/download/vX.Y.Z/mcp-server-X.Y.Z-<OS>-<ARCH>.<ext>
Example:      https://github.com/vernonkeenan/rosetta-mcp-server/releases/download/v0.1.2/mcp-server-0.1.2-darwin-arm64.tar.gz
                                                                                v0.1.2          0.1.2
                                                                                  ↑               ↑
                                                                              release tag    release version
```

Latest value at the time of writing: `TAG=v0.16.0`. See
CHANGELOG.md for the per-release content.

> **Historic note.** v0.1.0 and v0.1.1 shipped archives named
> `mcp-server-1.1.0-...` (the binary's API contract version, from
> the embedded OpenAPI). This caused operator confusion in an
> early tracker issue
> (#1).
> From v0.1.2 onwards the filename tracks the release tag.
> `mcp-server --version` exposes both numbers separately:
>
> ```
> mcp-server 0.16.0 (api 1.46.0)
>             ↑           ↑
>           release    API contract
> ```

> **Two download sources.** Each OS section below shows the
> primary GitHub Releases download. If you don't have GitHub
> access to the `rosetta-mcp-server` repo (it's private — cohort
> users typically don't), use the **§2b** "Alternative download"
> block immediately after step 2. The §2b form downloads from
> `https://rosetta-design.com/install/mcp/...` using your
> `ROSETTA_API_KEY` and is byte-identical to the GitHub Release.
> Pick one path; you only need one archive.

- [Linux](#linux)
- [macOS](#macos)
- [Windows](#windows)
- [Build from source](#build-from-source)
- [Register with a Claude surface](#register-with-a-claude-surface)
  - [Claude Code (CLI / IDE extension)](#claude-code-cli--ide-extension)
  - [Claude Desktop](#claude-desktop)
  - [Claude Cowork](#claude-cowork)
  - [claude.ai (web)](#claudeai-web)
- [Verify the install](#verify-the-install)
- [Troubleshooting](#troubleshooting)

---

## Linux

### 1. Identify your architecture

```bash
uname -m
# x86_64  → amd64   (Intel / AMD CPU)
# aarch64 → arm64   (ARM CPU; e.g., Raspberry Pi, AWS Graviton)
```

> **Note on `amd64`:** "amd64" is the OS-level name for the
> 64-bit Intel/AMD x86 architecture. It is **not** specific to
> AMD-brand CPUs — it covers Intel chips too. If `uname -m`
> reports `x86_64`, use `amd64`.

### 2. Download and extract

```bash
TAG=v0.16.0     # release tag
ARCH=amd64      # or arm64 (per Step 1)
curl -L -o mcp-server.tar.gz \
  "https://github.com/vernonkeenan/rosetta-mcp-server/releases/download/${TAG}/mcp-server-${TAG#v}-linux-${ARCH}.tar.gz"
tar xzf mcp-server.tar.gz
cd "mcp-server-${TAG#v}-linux-${ARCH}"
```

### 2b. Alternative download — rosetta-design.com (cohort users)

If you don't have GitHub access to the `rosetta-mcp-server` repo
(it's private), download from `rosetta-design.com` instead. Set
`ROSETTA_API_KEY` to the same `rsk_...` token you used to log
into rosetta-design.com (see "Before you start" §1):

```bash
TAG=v0.16.0     # release tag
ARCH=amd64      # or arm64
curl -fsSL -H "Authorization: Bearer ${ROSETTA_API_KEY}" \
  -o mcp-server.tar.gz \
  "https://rosetta-design.com/install/mcp/${TAG}/mcp-server-${TAG#v}-linux-${ARCH}.tar.gz"
tar xzf mcp-server.tar.gz
cd "mcp-server-${TAG#v}-linux-${ARCH}"
```

Skip §2b if step 2 succeeded — you only need one archive.

### 3. Install to `/usr/local/bin` (system-wide)

```bash
sudo install -m 0755 mcp-server /usr/local/bin/mcp-server
```

Or to `~/.local/bin` (no sudo, user-local):

```bash
mkdir -p ~/.local/bin
install -m 0755 mcp-server ~/.local/bin/mcp-server
# Make sure ~/.local/bin is on $PATH (most distros include it; if not):
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
```

### 4. Set your bearer token

```bash
echo 'export ROSETTA_AGENT_TOKEN="rsk_..."' >> ~/.bashrc
source ~/.bashrc
```

(Or `~/.zshrc` if you use Zsh.)

---

## macOS

### 1. Identify your architecture

```bash
uname -m
# x86_64 → amd64   (Intel Mac — pre-2020)
# arm64  → arm64   (Apple Silicon — M1, M2, M3, M4, ...)
```

> **Most modern Macs are Apple Silicon (`arm64`).** Any Mac with an
> "M" series chip (M1 / M2 / M3 / M4) is `arm64`. Pre-2020 Intel
> Macs are `amd64` (note: the `amd64` name refers to the 64-bit
> x86 instruction set, not specifically AMD-brand CPUs — Intel
> chips use it too).

### 2. Download and extract

```bash
TAG=v0.16.0     # release tag
ARCH=arm64      # or amd64 for pre-Apple-Silicon Intel Macs
curl -L -o mcp-server.tar.gz \
  "https://github.com/vernonkeenan/rosetta-mcp-server/releases/download/${TAG}/mcp-server-${TAG#v}-darwin-${ARCH}.tar.gz"
tar xzf mcp-server.tar.gz
cd "mcp-server-${TAG#v}-darwin-${ARCH}"
```

### 2b. Alternative download — rosetta-design.com (cohort users)

If you don't have GitHub access to the `rosetta-mcp-server` repo
(it's private), download from `rosetta-design.com` instead. Set
`ROSETTA_API_KEY` to the same `rsk_...` token you used to log
into rosetta-design.com (see "Before you start" §1):

```bash
TAG=v0.16.0     # release tag
ARCH=arm64      # or amd64
curl -fsSL -H "Authorization: Bearer ${ROSETTA_API_KEY}" \
  -o mcp-server.tar.gz \
  "https://rosetta-design.com/install/mcp/${TAG}/mcp-server-${TAG#v}-darwin-${ARCH}.tar.gz"
tar xzf mcp-server.tar.gz
cd "mcp-server-${TAG#v}-darwin-${ARCH}"
```

Skip §2b if step 2 succeeded — you only need one archive.

### 3. Clear the Gatekeeper quarantine

The binary is unsigned. macOS Gatekeeper will block it on first run
unless you remove the quarantine attribute:

```bash
xattr -d com.apple.quarantine mcp-server 2>/dev/null || true
```

(If you skip this, the first invocation gives "cannot be opened
because the developer cannot be verified.")

The `2>/dev/null || true` is required: a quarantine attribute is only
attached to **browser/GUI** downloads. A `curl` download has no
quarantine flag, so a bare `xattr -d com.apple.quarantine` exits **1**
("No such xattr") and aborts any `set -e` script or `&&` chain — even
though nothing is wrong. The guarded form is a no-op when the
attribute is absent.

### 4. Install

```bash
sudo install -m 0755 mcp-server /usr/local/bin/mcp-server
```

Or to `~/.local/bin`:

```bash
mkdir -p ~/.local/bin
install -m 0755 mcp-server ~/.local/bin/mcp-server
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```

### 5. Set your bearer token

```bash
echo 'export ROSETTA_AGENT_TOKEN="rsk_..."' >> ~/.zshrc
source ~/.zshrc
```

---

## Windows

### 1. Download the archive

In PowerShell:

```powershell
$TAG = "v0.16.0"                 # release tag
$VERSION = $TAG.TrimStart('v')    # 0.16.0 — used in the archive filename
$URL = "https://github.com/vernonkeenan/rosetta-mcp-server/releases/download/$TAG/mcp-server-$VERSION-windows-amd64.zip"
Invoke-WebRequest -Uri $URL -OutFile mcp-server.zip
```

Or download via your browser from the
Releases
page.

### 1b. Alternative download — rosetta-design.com (cohort users)

If you don't have GitHub access to the `rosetta-mcp-server` repo
(it's private), download from `rosetta-design.com` instead. Set
`ROSETTA_API_KEY` to the same `rsk_...` token you used to log
into rosetta-design.com (see "Before you start" §1):

```powershell
$TAG = "v0.16.0"                 # release tag
$VERSION = $TAG.TrimStart('v')    # 0.16.0
$URL = "https://rosetta-design.com/install/mcp/$TAG/mcp-server-$VERSION-windows-amd64.zip"
Invoke-WebRequest -Uri $URL -OutFile mcp-server.zip `
    -Headers @{ "Authorization" = "Bearer $env:ROSETTA_API_KEY" }
```

Skip §1b if §1 succeeded — you only need one archive.

### 2. Extract

```powershell
Expand-Archive mcp-server.zip -DestinationPath .
cd "mcp-server-$VERSION-windows-amd64"
```

### 3. Install to `%LOCALAPPDATA%\rosetta-mcp-server`

```powershell
$INSTALL_DIR = "$env:LOCALAPPDATA\rosetta-mcp-server"
New-Item -ItemType Directory -Force -Path $INSTALL_DIR | Out-Null
Copy-Item mcp-server.exe $INSTALL_DIR\
```

### 4. Add to user PATH

```powershell
$user_path = [Environment]::GetEnvironmentVariable("Path", "User")
if ($user_path -notlike "*$INSTALL_DIR*") {
    [Environment]::SetEnvironmentVariable("Path", "$user_path;$INSTALL_DIR", "User")
    Write-Host "Added $INSTALL_DIR to user PATH. Restart your terminal."
}
```

After restarting your terminal, `mcp-server` is on `$PATH`.

### 5. Set your bearer token

User-level environment variable (persists across sessions):

```powershell
[Environment]::SetEnvironmentVariable("ROSETTA_AGENT_TOKEN", "rsk_...", "User")
```

After this, restart your terminal so the new env var is loaded.

---

## Build from source

Requires Go 1.26+ and `make`.

```bash
git clone https://github.com/vernonkeenan/rosetta-mcp-server.git
cd rosetta-mcp-server
make build  # produces ./bin/mcp-server
```

The `Makefile` runs `make sync-embedded` before each build to refresh
`internal/embedded/` from the canonical sources.

For cross-platform builds:

```bash
make release-archives  # produces 5 archives in bin/release/
```

---

## Register with a Claude surface

The `mcpServers` JSON schema is **identical** across Claude Code,
Claude Desktop, and Claude Cowork. What differs is the file name
and location. Pick the section for your surface.

The reusable `mcpServers` block is in `.mcp.json` at the
repo root and in every release archive:

```json
{
  "mcpServers": {
    "rosetta": {
      "command": "mcp-server",
      "args": [],
      "env": {
        "ROSETTA_API_KEY": "${ROSETTA_AGENT_TOKEN}"
      }
    }
  }
}
```

Customizations apply identically on every surface:

| Customization | How |
|---------------|-----|
| Custom binary path (not on `$PATH`) | Change `"command"` to absolute path (e.g., `"/opt/rosetta/mcp-server"` on Linux/macOS, `"C:\\path\\to\\mcp-server.exe"` on Windows) |
| Different upstream REST API | Add `"ROSETTA_API_BASE": "https://your-host.example"` to the `env` block |
| Editable composites (no rebuild) | Add `"ROSETTA_MCP_COMPOSITES_DIR": "/path/to/dir"` to the `env` block; copy `composites.yaml` + `schema/composites.schema.json` to that directory |

### Claude Code (CLI / IDE extension)

Two registration scopes:

**Project-scoped** (recommended for most users; commits with the project):

```bash
cp /path/to/extracted/archive/.mcp.json /your/project/.mcp.json
cd /your/project
export ROSETTA_AGENT_TOKEN="rsk_..."
claude  # Claude Code picks up the rosetta_* tools
```

**User-scoped** (every Claude Code session, regardless of project):

```bash
claude mcp add rosetta mcp-server -e ROSETTA_API_KEY=$ROSETTA_AGENT_TOKEN
```

The `claude mcp add` command writes the registration into Claude
Code's user-level config so you don't have to hand-edit it. Verify:

```bash
claude mcp list
```

### Claude Desktop

Edit `claude_desktop_config.json` directly. Locations:

- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux:** Anthropic's Claude Desktop is currently macOS + Windows
  only; no Linux build at the time of writing. Use Claude Code instead.

> **macOS — opening the Library folder.** The `~/Library/` folder
> is **hidden by default** in Finder. Two ways to reach it:
>
> 1. In Finder, click **Go** in the menu bar, then **hold the
>    Option key** — a hidden "Library" item appears in the menu.
>    Click it.
> 2. Or in Finder press **⇧⌘G** (Shift+Cmd+G) and type
>    `~/Library/Application Support/Claude` and hit Return.
>
> If the file doesn't exist yet, you can create it as a plain text
> file. If it does exist, **preserve everything that's already in
> it** — Claude Desktop / Cowork add their own keys (e.g.,
> `preferences`) you must not overwrite.

Merge the `mcpServers` block into the file. If the file already has
other content, your edited version should look something like this
(your existing keys stay; you only **add** the `mcpServers` entry):

```json
{
  "preferences": {
    "coworkScheduledTasksEnabled": true,
    "ccdScheduledTasksEnabled": true,
    "sidebarMode": "task",
    "coworkWebSearchEnabled": true
  },
  "mcpServers": {
    "rosetta": {
      "command": "mcp-server",
      "args": [],
      "env": {
        "ROSETTA_API_KEY": "rsk_..."
      }
    }
  }
}
```

The `preferences` block above is what Claude Cowork / Claude
Desktop ship by default — **don't delete it**. Add `mcpServers`
alongside.

> **Hard-code the token, don't use `${VAR}` expansion in Claude
> Desktop / Cowork.** Replace `"rsk_..."` above with your actual
> bearer token (from
> [https://rosetta-design.com](https://rosetta-design.com) →
> Settings → API Keys). Claude Code expands `${ROSETTA_AGENT_TOKEN}`
> from your shell at MCP-server spawn time; Claude Desktop's
> behavior on this expansion is not guaranteed.
>
> Set file permissions to `600` (owner-read-write only) so other
> users on your machine can't read the token:
>
> ```bash
> # macOS:
> chmod 600 ~/Library/Application\ Support/Claude/claude_desktop_config.json
> ```

> **Restart required.** Claude Desktop reads the config **only at
> startup**. Quit the app fully (⌘Q on macOS, right-click tray
> icon → Quit on Windows) and reopen it after editing. Restarting
> a chat is not enough.

### Claude Cowork

Cowork runs inside Claude Desktop, so the registration is identical
to the Claude Desktop section above — same `claude_desktop_config.json`
file in the same OS-specific location. After editing, fully quit and
reopen the Desktop app; Cowork picks up the registered MCP servers
on the next launch.

### claude.ai (web)

Supported via the **Rosetta custom connector** at
`https://mcp.rosetta-design.com/mcp`. This path does **not** use
the local `mcp-server` binary — claude.ai connects directly to a
hosted MCP gateway. You can use this even if you never install
the binary on your laptop.

1. **claude.ai → Settings → Connectors → Add custom connector.**
2. Fill in:
   - **Name:** `Rosetta` (or whatever you like).
   - **URL:** `https://mcp.rosetta-design.com/mcp`
   - Leave the **Advanced** section blank.
3. Click **Add**, then **Connect** on the new connector tile.
4. claude.ai opens a tab at `mcp.rosetta-design.com/oauth/authorize`
   with an *"Authorize Rosetta connector"* page. **Paste your
   `rsk_*` API key** (the same one from rosetta-design.com →
   Settings → API Keys) and submit.
5. The tab closes; the connector tile in claude.ai shows
   **Connected**.

Smoke test in a new conversation: *"list the rosetta_\* tools"*.
You should see all 43 tools (5 composites + 38 1:1 wrappers).

> **How auth works under the hood.** Every tool call from
> claude.ai carries your `rsk_*` (wrapped in a short-lived OAuth
> envelope) and the gateway forwards it verbatim to the upstream
> rosetta-app-server. No shared operator key — your key, your
> audit trail, your rate limit. See
> `docs/decision-traces/dt-20260527-claude-ai-oauth-dcr.md`.

The local stdio install paths above (Claude Code, Claude Desktop,
Claude Cowork) remain the right choice when you want the binary
running on your own machine — for example, for offline work or
when targeting a non-prod rosetta-app-server.

---

For the richer registration that includes a `SKILL.md` teaching the
model when to call which tool, install the
`rosetta-agent` plugin — it carries
the same `mcpServers` block plus model-facing guidance and is
loaded by Claude Code's plugin system.

---

## Verify the install

### Binary is on PATH

```bash
mcp-server --help 2>&1 | head -1
# or just check `which mcp-server`
which mcp-server   # Linux/macOS
where.exe mcp-server   # Windows (PowerShell or cmd)
```

### Binary boots cleanly

```bash
ROSETTA_API_KEY="rsk_smoketest1234567890abcdefghij" mcp-server <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"0.0.1"}}}
{"jsonrpc":"2.0","id":2,"method":"tools/list"}
EOF
```

Expected output (stdout):

- A JSON-RPC `result` for `initialize` with
  `serverInfo.version` = `1.5.0` (the embedded OpenAPI's
  `info.version` — the same api number printed by
  `mcp-server --version`).
- A JSON-RPC `result` for `tools/list` with 43 tools (59 generated, 21
  hidden by the tool-exposure policy — see CHANGELOG v0.8.7).

stderr should show structured logs like:

```
{"level":"INFO","msg":"mcp gateway ready","rest_version":"1.5.0","tools":43,"base_url":"https://api.rosetta-design.com"}
```

### Verify checksums

Each release ships a `checksums.sha256`. The file lists one entry
per archive — match the line for the file you downloaded.

GitHub Releases users get it from the same release page. Cohort
users on the rosetta-design.com path fetch it the same way they
fetched the archive:

```bash
TAG=v0.16.0
curl -fsSL -H "Authorization: Bearer ${ROSETTA_API_KEY}" \
  -o checksums.sha256 \
  "https://rosetta-design.com/install/mcp/${TAG}/checksums.sha256"
```

Then verify the line for your archive:

```bash
# Linux: sha256sum is in coreutils.
sha256sum mcp-server-0.16.0-linux-amd64.tar.gz
# Compare against the matching line in checksums.sha256.

# macOS: use shasum -a 256.
shasum -a 256 mcp-server-0.16.0-darwin-arm64.tar.gz
# Compare against the matching line in checksums.sha256.

# Windows (PowerShell):
Get-FileHash mcp-server-0.16.0-windows-amd64.zip -Algorithm SHA256
# Compare against the matching line in checksums.sha256.
```

### Test against staging

If `ROSETTA_API_KEY` is a real bearer token issued by your
rosetta-app-server operator, the `tools/list` response carries
real route definitions. Try a `tools/call` against
`rosetta_get_authenticated_user` — it'll return your user profile
from the upstream:

```bash
ROSETTA_API_KEY="rsk_real_token_..." mcp-server <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"0.0.1"}}}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"rosetta_get_authenticated_user","arguments":{}}}
EOF
```

---

## Troubleshooting

### `mcp-server: command not found` (Linux/macOS)

The binary isn't on `$PATH`. Either the install step didn't put it
in a directory on your `$PATH`, or your shell hasn't been restarted
since you added the directory.

```bash
echo $PATH | tr ':' '\n'
# Confirm /usr/local/bin or ~/.local/bin appears.
```

### `'mcp-server' is not recognized as an internal or external command` (Windows)

User PATH was updated but the terminal session predates the change.
Close and reopen the terminal.

### macOS: `"mcp-server" cannot be opened because the developer cannot be verified.`

Gatekeeper quarantine wasn't cleared. Run:

```bash
xattr -d com.apple.quarantine /usr/local/bin/mcp-server 2>/dev/null || true
```

(Adjust the path if you installed elsewhere. The guard makes the
command a no-op when no quarantine flag is present — e.g. a `curl`
download — instead of exiting 1.)

### `ROSETTA_API_KEY is required`

The binary refuses to start without a bearer token. Make sure
`ROSETTA_AGENT_TOKEN` is set in your shell environment (or
`ROSETTA_API_KEY` directly if you're invoking the binary outside
Claude Code's plugin manifest).

### Claude Code doesn't see the `rosetta_*` tools

- Confirm `.mcp.json` is in the directory where you started Claude
  Code (not just any directory).
- Confirm the env block has `ROSETTA_API_KEY` resolving correctly
  (Claude Code expands `${ROSETTA_AGENT_TOKEN}` from your shell at
  spawn time — if the token isn't set in the env Claude Code sees,
  the binary fails fast).
- Try `claude mcp list` to confirm the server is registered at
  user scope.
- Check Claude Code's debug logs for MCP server spawn errors —
  `claude --debug` or the equivalent in your harness.

### Claude Desktop / Cowork doesn't see the `rosetta_*` tools

- Did you fully quit and reopen the app? Desktop reads the config
  **only at startup**; restarting a chat doesn't reload it.
- Confirm the JSON in `claude_desktop_config.json` is valid — a
  trailing comma or unclosed brace silently disables MCP loading.
  Validate via `python3 -m json.tool < claude_desktop_config.json`
  (Linux/macOS) or any JSON validator.
- If you used `${ROSETTA_AGENT_TOKEN}`, Claude Desktop may not
  expand it the way Claude Code does. Try hard-coding the token in
  the `env` block to confirm.
- Check Anthropic's debug logs for the desktop app — location
  varies by OS; see Anthropic's MCP troubleshooting guide.

### Upstream returns 401

The bearer token isn't recognized by the upstream. Check that:

- The token is for the `agent-harness` scope (not a different scope).
- The token hasn't been revoked or expired.
- `ROSETTA_API_BASE` is pointing at the right deployment (default
  `https://api.rosetta-design.com`).

### Network errors / connection refused

`ROSETTA_API_BASE` is unreachable. If you're testing against
production (`https://api.rosetta-design.com`) but it's down, override to
your local rosetta-app-server:

```bash
export ROSETTA_API_BASE="http://127.0.0.1:8081"
```

(or set it in `.mcp.json`'s `env` block).

---

For everything else, see [README](README.md) or open an issue.