dexe-setup
What this does
A guided onboarding journey for dexe-mcp. The plugin ships with sane public
defaults, so reads work the moment it's installed — no keys required. This
skill's job is to explain that reality and then help the user unlock the parts
that do need a key, one tier at a time, always saying what they lose by
skipping. It drives from the dexe_doctor tool — no guessing which file or key.
The two-tier reality (say this first)
Open by orienting the user:
Reads already work — DAO info, treasury, holders, proposals, subgraph
queries, IPFS reads all run on shared public defaults with zero setup.
You only need to configure something to write or to create DAOs/
proposals. Want me to walk you through it, or are reads all you need?
If reads are all they need: confirm they're done, mention dexe_doctor is there
if anything misbehaves, and stop.
When to invoke
- The user types
/dexe-setup.
- The user says "set up dexe", "enable writes", "I want to create a DAO/
proposal", "how do I configure dexe-mcp?".
- You see a tool result containing any of:
"DEXE_PINATA_JWT is required",
"Missing required env", "public RPC unstable", "public IPFS gateways are failing", env.sharedDefaults — invoke proactively.
Hard rules (do not violate)
- Never write
DEXE_* values to .claude.json. The MCP host's env block
SHADOWS .env silently. Write env to a .env file the server actually
loads. For a plugin / npx install that is ~/.dexe-mcp/.env (the
cwd-independent home config — works from any folder on any OS; same dir as
state.json). Only a source checkout uses the repo-root .env. Since
0.23.1 the server loads $DEXE_ENV_FILE → <cwd>/.env → ~/.dexe-mcp/.env
→ <pkgdir>/.env; the doctor/banner shows which file it loaded. Do NOT put
config in a project .env for plugin use — the plugin's working directory is
not your project, so it is silently missed.
- Never write
DEXE_PRIVATE_KEY without explicit user opt-in. Signing is
available by default via WalletConnect (below) — reach for a hot key only if
the user insists, and warn it lives in plaintext on disk.
- Always tell the user to restart Claude Code after editing
.env.
process.loadEnvFile() runs once at startup; mid-session edits do nothing
until restart.
- Cap the doctor loop at 3 iterations. After three doctor → fix → restart
cycles still failing, stop and present the full report for manual triage.
The setup tiers (walk in order; for each, state what breaks if skipped)
Tier 0 — Reads (nothing to do)
On-chain reads, subgraph reads, backend reads, IPFS reads all work on shared
public defaults. Skip cost: none. The only downside is the shared Graph API
key + public RPC/IPFS gateways are rate-limited and billable-shared — fine for
light use, upgrade under Tier 3 for heavy use.
Tier 1 — Signing (to vote / execute / broadcast)
WalletConnect is available by default (shared project id). To sign: run
dexe_wc_connect, scan the QR with a wallet, approve each tx on your phone. No
key touches disk.
- Skip cost: you can build calldata and read, but can't broadcast.
- Optional: set your own
DEXE_WALLETCONNECT_PROJECT_ID (free at
cloud.reown.com) to stop sharing the default id.
- Only if the user insists on unattended/CI signing → hot key ladder below.
Tier 2 — Creating DAOs / proposals (the one hard blocker)
Creating a DAO or proposal pins metadata to IPFS, which needs a Pinata JWT
(DEXE_PINATA_JWT). This is the only thing reads/signing can't default around.
- Skip cost:
dexe_dao_create, dexe_proposal_create, and metadata uploads
refuse up front (no on-chain tx is attempted).
- How to get one (say this to non-technical users): sign up free at
https://app.pinata.cloud → API Keys → New Key → enable
pinJSONToIPFS and
pinFileToIPFS → copy the JWT.
- Validate it before saving:
GET https://api.pinata.cloud/data/testAuthentication
with header Authorization: Bearer <jwt> should return {"message": "Congratulations! ..."}. (The npx dexe-mcp init wizard does this check for you.)
Tier 3 — Reliability upgrades (optional, offer when errors appear)
- Private RPC — if a read fails with "public RPC unstable": set
DEXE_RPC_URL_MAINNET (chain 56) / DEXE_RPC_URL_TESTNET (chain 97) to an
Alchemy / QuickNode / Ankr URL. Skip cost: occasional rate-limit flakiness.
- Dedicated IPFS gateway — if a read fails with "public IPFS gateways are
failing": set
DEXE_IPFS_GATEWAY (a free Pinata dedicated gateway comes with
your JWT — https://<subdomain>.mypinata.cloud). Skip cost: slower/flaky
metadata reads.
- Own Graph key — if
dexe_doctor shows env.sharedDefaults: set your own
DEXE_SUBGRAPH_*_URL (with your Graph key embedded, or DEXE_GRAPH_API_KEY).
Skip cost: you share a rate-limited, billable key.
Algorithm
- Call
dexe_doctor (no input).
- Read
summary and checks from the structured response.
- Success is
summary.failures === 0 — equivalently summary.advisoryOnly
when there are warnings. Reads are healthy; ask which tier (if any) the user
wants, and don't block on warnings.
summary.status === "pass" means zero warnings AND zero failures. A
zero-config install always carries warnings (public RPC, shared defaults),
so status is "warn" there and never reaches "pass" — treating it as
the success test loops fix → restart forever with nothing left to fix.
- Treat
warn checks (chain.publicRpcFallback, env.sharedDefaults) as
offers, not problems.
- For each
fail or the user's chosen tier, collect the env key(s). Use the
check's remediation verbatim for network failures.
- Batch questions by tier/category with
AskUserQuestion — one question per
tier, not one per key. Only ask for what the chosen tier needs.
- Locate the
.env the server loads (the doctor/banner shows the path). For a
plugin/npx install use ~/.dexe-mcp/.env (create the .dexe-mcp dir if
absent); for a source checkout use the repo-root .env (where package.json
lives). When unsure, prefer ~/.dexe-mcp/.env — it loads on every OS from any
folder.
- Edit that
.env with the Edit tool: replace the key's line if present, else
append KEY=value (preserve the trailing newline).
- Tell the user, verbatim:
Edits saved to .env. Restart Claude Code so the new values load
(quit and relaunch). Then I'll re-run dexe_doctor to confirm.
- After restart, re-run
dexe_doctor. If still failing, go to step 3. Iterate
at most 3 times.
- After 3 iterations still failing, present the full
checks array — remaining
issues need manual triage (bad credentials, suspended account, paid-plan
required, corporate proxy).
Signer mode escalation
If the user wants signing beyond phone-approval WalletConnect, walk this ladder
(top = safest):
- WalletConnect (default).
dexe_wc_connect → approve on phone. No key on
disk. This is already available; prefer it — and it is the only right
answer when this agent can run shell commands or drive a browser.
- Encrypted keystore (
DEXE_SIGNER_MODE=keystore). The USER runs
npx dexe-mcp key create (or key import, or key import --from-env to
move an existing DEXE_PRIVATE_KEY) in their own terminal — it needs a TTY
and will refuse your shell. Then .env gets DEXE_SIGNER_MODE=keystore.
Each write opens a local approval page; the user types the password THERE.
Never ask for, accept, or relay the keystore password. On
awaiting_approval, tell the user to approve, then re-run the same call.
See docs/SIGNING.md.
- Safe multisig (
DEXE_SAFE_TX_SERVICE_URL). Proposes tx to a Safe; owners
co-sign separately.
- Unattended hot key (
DEXE_SIGNER_MODE=unattended + DEXE_PRIVATE_KEY).
Plaintext on disk, no confirmation, testnet only unless
DEXE_UNATTENDED_CHAINS lists more. For CI bots, dangerous for humans. Show
this before writing:
Setting DEXE_PRIVATE_KEY stores your key in plaintext at .env, and in
unattended mode it signs with no confirmation. Anyone who reads the file
can drain that wallet. Are you sure you don't want WalletConnect (already
available) or the encrypted keystore instead?
- Refuse to proceed to a hot key without an explicit "yes" confirming the
trade-off, and always write
DEXE_SIGNER_MODE=unattended with it (with the
mode unset, a hot key is ignored).
.env precedence trap
If dexe_doctor returns a check named env.<KEY> with "shadowed by host env
block", the same key is defined in BOTH .env and .claude.json. The host
wins. Tell them to keep it in one place (prefer .env) and restart.
Useful tools (reference)
dexe_doctor — diagnostic (read-only, safe to call repeatedly).
dexe_context — env readiness + usingSharedDefaults list.
dexe_write_context — signer/mode, keyring, Pinata / WalletConnect / Safe posture.
npx dexe-mcp doctor — CLI form; useful when the MCP server failed to start.
It exits 0 when nothing failed (warnings included), 2 on a real failure
or an unknown flag; pass --strict (or set DEXE_DOCTOR_STRICT=1) to make
warnings exit 1 instead, which is what a CI gate wants and a setup session
does not.
npx dexe-mcp init — fresh-start wizard (prompts + live-validates Pinata JWT).
Overwrites .env; use for new installs, not for fixing an existing setup.
1---2name: dexe-setup3description: |4 Guided setup journey for dexe-mcp. Explains that reads work with ZERO config,5 then walks the user through only the keys that unlock more — signing, DAO/6 proposal creation (Pinata JWT), and optional reliability upgrades — telling7 them for each one exactly what breaks if they skip it. Drives from8 `dexe_doctor`, edits `.env` (NEVER `.claude.json`), and tells them to restart.9 Triggered by `/dexe-setup`, or proactively when a tool reports a missing key10 ("DEXE_PINATA_JWT is required…", "public RPC unstable", "shared public defaults").11metadata:12 source: https://skillmd.com/skills/jiayaoqijia/dexe-setup13---1415# dexe-setup1617## What this does1819A guided onboarding journey for `dexe-mcp`. The plugin ships with sane public20defaults, so **reads work the moment it's installed** — no keys required. This21skill's job is to explain that reality and then help the user unlock the parts22that *do* need a key, one tier at a time, always saying what they lose by23skipping. It drives from the `dexe_doctor` tool — no guessing which file or key.2425## The two-tier reality (say this first)2627Open by orienting the user:2829> **Reads already work** — DAO info, treasury, holders, proposals, subgraph30> queries, IPFS reads all run on shared public defaults with zero setup.31> You only need to configure something to **write** or to **create DAOs/32> proposals**. Want me to walk you through it, or are reads all you need?3334If reads are all they need: confirm they're done, mention `dexe_doctor` is there35if anything misbehaves, and stop.3637## When to invoke3839- The user types `/dexe-setup`.40- The user says "set up dexe", "enable writes", "I want to create a DAO/41 proposal", "how do I configure dexe-mcp?".42- You see a tool result containing any of: `"DEXE_PINATA_JWT is required"`,43 `"Missing required env"`, `"public RPC unstable"`, `"public IPFS gateways44 are failing"`, `env.sharedDefaults` — invoke proactively.4546## Hard rules (do not violate)47481. **Never write `DEXE_*` values to `.claude.json`.** The MCP host's env block49 SHADOWS `.env` silently. Write env to a `.env` file the server actually50 loads. For a **plugin / `npx` install** that is **`~/.dexe-mcp/.env`** (the51 cwd-independent home config — works from any folder on any OS; same dir as52 `state.json`). Only a **source checkout** uses the repo-root `.env`. Since53 0.23.1 the server loads `$DEXE_ENV_FILE` → `<cwd>/.env` → `~/.dexe-mcp/.env`54 → `<pkgdir>/.env`; the doctor/banner shows which file it loaded. Do NOT put55 config in a project `.env` for plugin use — the plugin's working directory is56 not your project, so it is silently missed.572. **Never write `DEXE_PRIVATE_KEY` without explicit user opt-in.** Signing is58 available by default via WalletConnect (below) — reach for a hot key only if59 the user insists, and warn it lives in plaintext on disk.603. **Always tell the user to restart Claude Code after editing `.env`.**61 `process.loadEnvFile()` runs once at startup; mid-session edits do nothing62 until restart.634. **Cap the doctor loop at 3 iterations.** After three doctor → fix → restart64 cycles still failing, stop and present the full report for manual triage.6566## The setup tiers (walk in order; for each, state what breaks if skipped)6768### Tier 0 — Reads (nothing to do)69On-chain reads, subgraph reads, backend reads, IPFS reads all work on shared70public defaults. **Skip cost: none.** The only downside is the shared Graph API71key + public RPC/IPFS gateways are rate-limited and billable-shared — fine for72light use, upgrade under Tier 3 for heavy use.7374### Tier 1 — Signing (to vote / execute / broadcast)75WalletConnect is **available by default** (shared project id). To sign: run76`dexe_wc_connect`, scan the QR with a wallet, approve each tx on your phone. No77key touches disk.78- **Skip cost:** you can build calldata and read, but can't broadcast.79- Optional: set your own `DEXE_WALLETCONNECT_PROJECT_ID` (free at80 cloud.reown.com) to stop sharing the default id.81- Only if the user *insists* on unattended/CI signing → hot key ladder below.8283### Tier 2 — Creating DAOs / proposals (the one hard blocker)84Creating a DAO or proposal pins metadata to IPFS, which needs a **Pinata JWT**85(`DEXE_PINATA_JWT`). This is the only thing reads/signing can't default around.86- **Skip cost:** `dexe_dao_create`, `dexe_proposal_create`, and metadata uploads87 refuse up front (no on-chain tx is attempted).88- How to get one (say this to non-technical users): sign up free at89 https://app.pinata.cloud → API Keys → New Key → enable `pinJSONToIPFS` and90 `pinFileToIPFS` → copy the JWT.91- Validate it before saving: `GET https://api.pinata.cloud/data/testAuthentication`92 with header `Authorization: Bearer <jwt>` should return `{"message":93 "Congratulations! ..."}`. (The `npx dexe-mcp init` wizard does this check for you.)9495### Tier 3 — Reliability upgrades (optional, offer when errors appear)96- **Private RPC** — if a read fails with *"public RPC unstable"*: set97 `DEXE_RPC_URL_MAINNET` (chain 56) / `DEXE_RPC_URL_TESTNET` (chain 97) to an98 Alchemy / QuickNode / Ankr URL. **Skip cost:** occasional rate-limit flakiness.99- **Dedicated IPFS gateway** — if a read fails with *"public IPFS gateways are100 failing"*: set `DEXE_IPFS_GATEWAY` (a free Pinata dedicated gateway comes with101 your JWT — `https://<subdomain>.mypinata.cloud`). **Skip cost:** slower/flaky102 metadata reads.103- **Own Graph key** — if `dexe_doctor` shows `env.sharedDefaults`: set your own104 `DEXE_SUBGRAPH_*_URL` (with your Graph key embedded, or `DEXE_GRAPH_API_KEY`).105 **Skip cost:** you share a rate-limited, billable key.106107## Algorithm1081091. Call `dexe_doctor` (no input).1102. Read `summary` and `checks` from the structured response.111 - **Success is `summary.failures === 0`** — equivalently `summary.advisoryOnly`112 when there are warnings. Reads are healthy; ask which tier (if any) the user113 wants, and don't block on warnings.114 - `summary.status === "pass"` means zero warnings AND zero failures. A115 zero-config install always carries warnings (public RPC, shared defaults),116 so `status` is `"warn"` there and never reaches `"pass"` — treating it as117 the success test loops fix → restart forever with nothing left to fix.118 - Treat `warn` checks (`chain.publicRpcFallback`, `env.sharedDefaults`) as119 *offers*, not problems.1203. For each `fail` or the user's chosen tier, collect the env key(s). Use the121 check's `remediation` verbatim for network failures.1224. Batch questions by tier/category with `AskUserQuestion` — one question per123 tier, not one per key. Only ask for what the chosen tier needs.1245. Locate the `.env` the server loads (the doctor/banner shows the path). For a125 plugin/`npx` install use `~/.dexe-mcp/.env` (create the `.dexe-mcp` dir if126 absent); for a source checkout use the repo-root `.env` (where `package.json`127 lives). When unsure, prefer `~/.dexe-mcp/.env` — it loads on every OS from any128 folder.1296. Edit that `.env` with the Edit tool: replace the key's line if present, else130 append `KEY=value` (preserve the trailing newline).1317. Tell the user, verbatim:132 > Edits saved to `.env`. **Restart Claude Code** so the new values load133 > (quit and relaunch). Then I'll re-run `dexe_doctor` to confirm.1348. After restart, re-run `dexe_doctor`. If still failing, go to step 3. Iterate135 at most 3 times.1369. After 3 iterations still failing, present the full `checks` array — remaining137 issues need manual triage (bad credentials, suspended account, paid-plan138 required, corporate proxy).139140## Signer mode escalation141142If the user wants signing beyond phone-approval WalletConnect, walk this ladder143(top = safest):1441451. **WalletConnect (default).** `dexe_wc_connect` → approve on phone. No key on146 disk. This is already available; prefer it — and it is the only right147 answer when this agent can run shell commands or drive a browser.1482. **Encrypted keystore (`DEXE_SIGNER_MODE=keystore`).** The USER runs149 `npx dexe-mcp key create` (or `key import`, or `key import --from-env` to150 move an existing `DEXE_PRIVATE_KEY`) in their own terminal — it needs a TTY151 and will refuse your shell. Then `.env` gets `DEXE_SIGNER_MODE=keystore`.152 Each write opens a local approval page; the user types the password THERE.153 **Never ask for, accept, or relay the keystore password.** On154 `awaiting_approval`, tell the user to approve, then re-run the same call.155 See docs/SIGNING.md.1563. **Safe multisig (`DEXE_SAFE_TX_SERVICE_URL`).** Proposes tx to a Safe; owners157 co-sign separately.1584. **Unattended hot key (`DEXE_SIGNER_MODE=unattended` + `DEXE_PRIVATE_KEY`).**159 Plaintext on disk, no confirmation, testnet only unless160 `DEXE_UNATTENDED_CHAINS` lists more. For CI bots, dangerous for humans. Show161 this before writing:162 > Setting `DEXE_PRIVATE_KEY` stores your key in plaintext at `.env`, and in163 > unattended mode it signs with no confirmation. Anyone who reads the file164 > can drain that wallet. Are you sure you don't want WalletConnect (already165 > available) or the encrypted keystore instead?1665. Refuse to proceed to a hot key without an explicit "yes" confirming the167 trade-off, and always write `DEXE_SIGNER_MODE=unattended` with it (with the168 mode unset, a hot key is ignored).169170## .env precedence trap171172If `dexe_doctor` returns a check named `env.<KEY>` with "shadowed by host env173block", the same key is defined in BOTH `.env` and `.claude.json`. The host174wins. Tell them to keep it in one place (prefer `.env`) and restart.175176## Useful tools (reference)177178- `dexe_doctor` — diagnostic (read-only, safe to call repeatedly).179- `dexe_context` — env readiness + `usingSharedDefaults` list.180- `dexe_write_context` — signer/mode, keyring, Pinata / WalletConnect / Safe posture.181- `npx dexe-mcp doctor` — CLI form; useful when the MCP server failed to start.182 It exits **0** when nothing failed (warnings included), **2** on a real failure183 or an unknown flag; pass `--strict` (or set `DEXE_DOCTOR_STRICT=1`) to make184 warnings exit **1** instead, which is what a CI gate wants and a setup session185 does not.186- `npx dexe-mcp init` — fresh-start wizard (prompts + live-validates Pinata JWT).187 Overwrites `.env`; use for new installs, not for fixing an existing setup.