bifrost-mcp-setup · diff
git:20260708.31973bb to git:20260718.17f3337
18 added, 80 removed. Audit A to A.
---
name: bifrost-mcp-setup
- description: "Manually wire a Bifrost MCP server into Claude Code (mcp.json) or Claude Desktop (OAuth connector or local proxy) when the automated installer can't run. Triggers on 'manually add bifrost mcp', 'edit mcp.json for bifrost', 'installer failed', 'add x-bf-vk header', 'manual bifrost setup', 'mcp.json bifrost', 'bifrost in claude desktop', 'claude_desktop_config'."
+ description: "Manually wire a Bifrost MCP server into Claude Code when the automated installer can't run. Triggers on 'manually add bifrost mcp', 'installer failed', 'add x-bf-vk header', 'manual bifrost setup', 'register bifrost mcp'."
---
# Manual Bifrost MCP Setup
Use this when the automated installer (`node bin/install.js` / `/bifrost-setup`)
can't run (no internet, policy restriction, etc.).
+ Note: if the plugin itself is installed and enabled, none of this is needed —
+ the plugin's shipped `.mcp.json` registers the `bifrost` server automatically.
+ This skill is for wiring the MCP server WITHOUT the plugin.
+
## Step 1 — Set your gateway URL and virtual key
```bash
# Add to ~/.zshrc or ~/.bashrc (replace with your real values):
export BIFROST_URL=https://<your-gateway-host>/mcp
export BIFROST_VK=vk_<your-key>
source ~/.zshrc # or ~/.bashrc
```
Never commit the VK. It belongs in your shell env only.
- ## Step 2 — Edit ~/.claude/mcp.json
-
- Open `~/.claude/mcp.json` (create it if it doesn't exist) and merge in the
- bifrost server block. The `${BIFROST_URL}` and `${BIFROST_VK}` placeholders are
- resolved at runtime from your shell env:
-
- ```json
- {
- "mcpServers": {
- "bifrost": {
- "type": "http",
- "url": "${BIFROST_URL}",
- "headers": { "x-bf-vk": "${BIFROST_VK}" }
- }
- }
- }
- ```
-
- If the file already has other servers under `mcpServers`, add `"bifrost": { … }`
- alongside them — do not overwrite the whole file.
-
- Quick one-liner to add it (uses node for safe JSON merge):
+ ## Step 2 — Register the server with the Claude Code CLI
```bash
- node -e "
- const fs = require('fs'), os = require('os');
- const f = os.homedir() + '/.claude/mcp.json';
- let cfg = {};
- try { cfg = JSON.parse(fs.readFileSync(f, 'utf8')); } catch {}
- cfg.mcpServers = cfg.mcpServers || {};
- if (cfg.mcpServers.bifrost) { console.log('bifrost already present — no change'); process.exit(0); }
- cfg.mcpServers.bifrost = {
- type: 'http',
- url: '\${BIFROST_URL}',
- headers: { 'x-bf-vk': '\${BIFROST_VK}' }
- };
- fs.writeFileSync(f, JSON.stringify(cfg, null, 2));
- console.log('bifrost added to', f);
- "
+ claude mcp add --scope user --transport http bifrost \
+ "${BIFROST_URL}" --header 'x-bf-vk: ${BIFROST_VK}'
```
+ The single-quoted `${BIFROST_VK}` is stored as a runtime template — Claude Code
+ resolves it from your shell env on every launch, so the key itself is never
+ written to disk. Re-running the command replaces the same entry (idempotent).
+
## Step 3 — Restart Claude Code
- Changes to `~/.claude/mcp.json` take effect only after a CC restart.
+ MCP registration changes take effect only after a CC restart.
## Step 4 — Verify
```bash
# Confirm the entry is present:
- node -e "const m=require(require('os').homedir()+'/.claude/mcp.json'); console.log(JSON.stringify(m.mcpServers.bifrost, null, 2))"
+ claude mcp get bifrost
# Confirm env vars are set:
echo "URL: ${BIFROST_URL:-NOT SET}"
echo "VK: ${BIFROST_VK:+set (${#BIFROST_VK} chars)}${BIFROST_VK:-NOT SET}"
```
If your gateway exposes a skill server, then inside Claude Code call
`mcp__bifrost__<skills-server>-skill_search` with `"test"` — if it returns
results, the gateway is live.
- ## Claude Desktop
-
- Desktop does **not** read `~/.claude/mcp.json` and has no header field for a
- virtual key — it connects via OAuth (preferred) or a local proxy (fallback).
-
- ### Preferred — OAuth connector
-
- 1. **Settings → Connectors → Add custom connector**, URL:
- `https://<stable-gateway-host>/mcp` (the stable domain — ephemeral tunnel
- URLs won't work with OAuth).
- 2. Connect → log in at the company Keycloak → consent. No key or config file needed.
- 3. If the connector cannot self-register (`mcp_registration_failed` despite a
- correct URL), enter the operator-provided client ID under
- **Advanced settings → OAuth Client ID**.
-
- ### Fallback — local `mcp-remote` proxy
-
- Only if the OAuth bridge is not deployed. Requires Node. Edit
- `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or
- `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+ ## Uninstall
- ```json
- {
- "mcpServers": {
- "bifrost": {
- "command": "npx",
- "args": [
- "mcp-remote", "https://<stable-gateway-host>/mcp",
- "--transport", "http-only",
- "--header", "x-bf-vk:${BIFROST_VK}"
- ],
- "env": { "BIFROST_VK": "vk_<your-key>" }
- }
- }
- }
+ ```bash
+ claude mcp remove --scope user bifrost
```
- No spaces around `:` in the `--header` arg. This file then contains your key —
- treat it as a secret (`chmod 600` on macOS/Linux) and never commit it.
- Restart Claude Desktop afterwards.
-
## Troubleshooting
- **401 from bifrost** → `BIFROST_VK` is wrong or not exported. Re-check your shell env.
- - **Tool not found after restart** → confirm `~/.claude/mcp.json` has `"type":"http"` (not `"sse"`).
+ - **Tool not found after restart** → `claude mcp get bifrost` should show `"type": "http"` (not `"sse"`); re-run Step 2 if the entry is missing.
- **Gateway timeout** → gateway may be offline or `BIFROST_URL` is wrong. Contact the gateway operator.
- - **Desktop OAuth errors** (`mcp_registration_failed`, `Invalid redirect URI`, `no_virtual_key`) → run `/bifrost-debug` step 7.
For full diagnosis: `/bifrost-debug`.