---
name: oracle-mcp-install
description: Use when installing Oracle as an MCP server in AI clients.
---

> Oracle native tools: `oracle_cli` (read/prepare), `vault_status`, `signer_status`, `signer_execute` (needs human confirmationNonce), `skill_load`. No generic shell. No fleet SSH.


# Oracle MCP install

## Quick start

```bash
oracle bootstrap
oracle init --apply              # generates wallet, starts services
oracle mcp install claude-code --with-soul
```

Public MCP is **data + prepare** only:

| Server | Purpose |
|---|---|
| `oracle-data` | Read prices, quotes, routes, prepare unsigned tx |

Signing stays on the user's machine (`oracle sign` / loopback signer). Do not wire a remote control/exec MCP from this public skill.

`--with-soul` injects the Oracle SOUL.md as system instructions so Claude/Cursor/etc.
think like Oracle — same routing logic, chain laws, safety gates.

**Target-specific behavior:**

| Target | Method | File written |
|---|---|---|
| `claude-code` | Prepends SOUL before existing CLAUDE.md | `./CLAUDE.md` |
| `claude-desktop` | Prepends SOUL to customInstructions in config | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| `cursor` | Prepends SOUL before existing .cursorrules | `./.cursorrules` |
| `vscode` | Writes SOUL to Copilot instructions | `./.vscode/instructions.md` |
| `codex` / `copilot` | Writes SOUL to Copilot instructions | `./.github/copilot-instructions.md` |
| `chatgpt` | Not supported (returns ok:false) | — |

All paths prepend the SOUL before existing content (preserves user's existing rules).
On dry-run (`--print`), shows the first 500 chars of what would be written.

## Standalone gateway (no Hermes)

```bash
oracle setup telegram    # bot token → Grammy poller
oracle setup discord     # bot token → discord.js
oracle setup whatsapp    # QR code scan → whatsapp-web.js (auto-installs deps)
oracle setup signal      # signal-cli (stub)
```

Oracle polls messaging APIs directly — no Hermes gateway required. All platforms
share one process (`oracle gateway` on port 9270), using Oracle's own agent runtime.
Auto-detects Hermes/OpenClaw and uses whichever is available; falls back to
Oracle standalone polling if neither is present.

For WhatsApp: first run auto-installs `whatsapp-web.js` + `qrcode-terminal`,
shows a QR code for pairing. Session persists in `~/.config/oracle/.wwebjs_auth`.

## Supported targets

| Command | Target config | Method |
|---|---|---|
| `oracle mcp install claude-code` | `~/.claude.json` | `claude mcp add-json` CLI, fallback: mergeMcpServers |
| `oracle mcp install claude-desktop` | Claude Desktop config | mergeMcpServers |
| `oracle mcp install chatgpt` | ChatGPT connector | Custom installer |
| `oracle mcp install codex` | OpenAI Codex CLI | Config file merge |
| `oracle mcp install copilot` | *(alias for codex)* | Same as codex |
| `oracle mcp install cursor` | `~/.config/cursor/mcp.json` | mergeMcpServers (Linux), platform-aware path |
| `oracle mcp install vscode` | `.vscode/mcp.json` or global | mergeMcpServers (`--project` for workspace) |

## Flags

| Flag | Effect |
|---|---|
| `--with-soul` | Injects Oracle SOUL.md into the harness as system instructions |
| `--project` | VS Code: writes to workspace `.vscode/mcp.json` instead of global |
| `--print` | Dry-run: shows what would be written, makes no changes |
| `--json` | Machine-readable output for install results |

## Watchdog

```bash
oracle mcp watchdog          # background: checks every 2m, warns if MCP servers down
oracle mcp watchdog --once   # one-shot health check
```

## Wallet setup

```bash
oracle sign init [--passphrase-file <0600 file>]
oracle sign import --kind evm --key-file <0600 file> [--passphrase-file <0600 file>]
oracle sign import --kind btc --key-file <0600 file> [--passphrase-file <0600 file>]
oracle sign import --kind sol --key-file <0600 file> [--passphrase-file <0600 file>]
oracle sign policy --policy-file <0600 JSON file>
oracle sign status
oracle sign doctor
```

The passphrase comes from a hidden TTY prompt or an owner-only file. Key material comes only
from `--key-file`; Oracle refuses private keys in arguments and inherited environment variables.
The encrypted keyring lives at `<config>/signer/vault.json`. Importing leaves the vault
locked rather than armed, but it does not sign, execute, submit, trade, or broadcast. The
owner lifts the lock as a separate step with `oracle sign unlock --acknowledge-local-signing`.
An explicit command asks for confirmation before
signing, executing, or broadcasting. The only same-turn shortcut is to say `quick transaction`
and explicitly confirm in the same sentence. An explicitly configured autonomous grant, such
as a shadow-profit promotion rule, is the separate exception. Signing still requires a sealed
policy with nonempty allowlists and a short-lived signer session. Public follows Administrator
execution behavior and applies the disclosed public fees.
Never ask users to paste private keys into chat, app UI, or shell arguments.

## Print mode
```
oracle mcp print claude-code     → shows JSON without writing
oracle mcp print --target cursor → same for any target
```

## Autofill behavior
Every target auto-detects the user's config, merges Oracle's MCP server specs
(`oracle-data`), backs up the original with
`.bak-oracle-<timestamp>`, and reports the result. No manual JSON required.

## Adding a new target
1. Create `src/cli/mcp-targets/<name>.mjs`
2. Export `install<Name>({ oracleRoot, operator, withControl, project, printOnly, cwd })`
3. Import `buildServerSpecs`, `mergeMcpServers`, `report` from `./shared.mjs`
4. Import in `src/cli/commands/mcp.mjs`
5. Add to the install switch and `usage()` text

## Pitfalls
- `ORACLE_DESK_URL` is not used for MCP — the spec points at the local binary
- Cursor/VS Code paths differ by OS
- VS Code `--project` writes workspace `.vscode/mcp.json`, not global
- After adding a target, verify `oracle mcp print --target <name>` on the installed binary
- Signing is local. Do not document a remote control/exec MCP in the public pack