Installing rosetta-mcp-server¶

Per-platform install walkthroughs for the rosetta-mcp-server 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:

A bearer token (ROSETTA_API_KEY). Register at 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.
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.8.10. 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.8.1 (api 1.3.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
macOS
Windows
Build from source
Register with a Claude surface
Claude Code (CLI / IDE extension)
Claude Desktop
Claude Cowork
claude.ai (web)
Verify the install
Troubleshooting

Linux¶

1. Identify your architecture¶

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¶

TAG=v0.8.10      # 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):

TAG=v0.8.10      # 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)¶

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

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

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¶

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

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

macOS¶

1. Identify your architecture¶

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¶

TAG=v0.8.10      # 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):

TAG=v0.8.10      # 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:

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¶

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

Or to ~/.local/bin:

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¶

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

Windows¶

1. Download the archive¶

In PowerShell:

$TAG = "v0.8.10"                  # release tag
$VERSION = $TAG.TrimStart('v')    # 0.8.10 — 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):

$TAG = "v0.8.10"                  # release tag
$VERSION = $TAG.TrimStart('v')    # 0.8.10
$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¶

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

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

$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¶

$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):

[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.

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:

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:

{
  "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):

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):

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:

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:

In Finder, click Go in the menu bar, then hold the Option key — a hidden "Library" item appears in the menu. Click it.

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):

{
  "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 → 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:
# 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.

claude.ai → Settings → Connectors → Add custom connector.
Fill in:
Name: Rosetta (or whatever you like).
URL: https://mcp.rosetta-design.com/mcp
Leave the Advanced section blank.
Click Add, then Connect on the new connector tile.
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.
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¶

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¶

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:

TAG=v0.8.10
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:

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

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

# Windows (PowerShell):
Get-FileHash mcp-server-0.8.10-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:

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.

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:

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:

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

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

For everything else, see README or open an issue.

Installing rosetta-mcp-server¶

Before you start¶

Version cheatsheet¶

Linux¶

1. Identify your architecture¶

2. Download and extract¶

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

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

4. Set your bearer token¶

macOS¶

1. Identify your architecture¶

2. Download and extract¶

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

3. Clear the Gatekeeper quarantine¶

4. Install¶

5. Set your bearer token¶

Windows¶

1. Download the archive¶

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

2. Extract¶

3. Install to %LOCALAPPDATA%\rosetta-mcp-server¶

4. Add to user PATH¶

5. Set your bearer token¶

Build from source¶

Register with a Claude surface¶

Claude Code (CLI / IDE extension)¶

Claude Desktop¶

Claude Cowork¶

claude.ai (web)¶

Verify the install¶

Binary is on PATH¶

Binary boots cleanly¶

Verify checksums¶

Test against staging¶

Troubleshooting¶

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

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

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

ROSETTA_API_KEY is required¶

Claude Code doesn't see the rosetta_* tools¶

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

Upstream returns 401¶

Network errors / connection refused¶

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

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

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

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

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

`ROSETTA_API_KEY is required`¶

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

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