| name | clio-setup |
| description | Walk the user through one-time setup of the Clio Manage MCP server — Clio developer app, OAuth credentials, env vars, first authorization, and a smoke test. Use when the user has just installed the plugin, when /mcp shows clio-manage failing to connect, when the user asks "how do I set up the Clio MCP", "configure Clio", "connect Clio to Claude", "get started with Clio Manage MCP", or when CLIO_CLIENT_ID / CLIO_CLIENT_SECRET are not set. |
| argument-hint | [--region us|ca|eu|au] |
Setup the Clio Manage MCP
Take the user from zero to a working Clio MCP. Default to the local stdio
path; mention Azure only if they ask or if you detect Azure infra files.
Pre-flight
Check whether each of these is already true before asking anything:
test -f "$PWD/build/index.js" && echo built
grep -E "^CLIO_CLIENT_ID=" .env 2>/dev/null
test -d "${CLIO_STATE_DIR:-$HOME/.clio-manage-mcp}" || test -d "$HOME/.clio-mcp"
If build/index.js is missing, run npm install && npm run build first.
Walk the user through these steps
1. Create a Clio developer app
Send them to the region-specific developer portal:
Tell them:
- App type: Web app
- Redirect URI:
http://127.0.0.1:5678/callback (must match the server's
loopback callback exactly — Clio is strict). The port defaults to 5678;
override it with CLIO_REDIRECT_PORT and register the matching URI.
- Scopes: leave default (full) unless they have firm policy
- Save the client ID and client secret
2. Fill in .env
If .env doesn't exist, copy from the example:
cp .env.example .env
Then prompt for and edit the values. Required:
CLIO_CLIENT_ID=...
CLIO_CLIENT_SECRET=...
CLIO_ENCRYPTION_KEY=... # 64 hex chars — generate in step 3
CLIO_REGION=us
Don't write the secret to chat. Use Edit to put it directly into .env.
3. Generate the token encryption key
openssl rand -hex 32
Put the output in .env as CLIO_ENCRYPTION_KEY=.... This is required:
it must be exactly 64 hex characters (32 bytes) — the AES-256-GCM key the
server uses to encrypt the Clio token blob at rest. The server refuses to
start without it. Use the same key across machines so a saved token blob
stays readable.
4. Run the one-time OAuth flow
npm run start:stdio
In another terminal, run any MCP client (Claude Code itself, MCP inspector,
or the smoke test) and call clio_authenticate. The MCP opens a browser tab,
the user signs in to Clio, Clio redirects back to 127.0.0.1:5678, the MCP
captures the code, exchanges it for tokens, and writes them encrypted to
$CLIO_STATE_DIR/tokens.enc.
Verify:
ls -la "${CLIO_STATE_DIR:-$HOME/.clio-manage-mcp}"
5. Smoke test
npm run smoke:stdio
A passing run prints OK and the tool count (≥ 41).
6. Wire Claude Code at the plugin
The plugin's .mcp.json launches the server with npx github:..., so no
manual build is needed — just export CLIO_CLIENT_ID, CLIO_CLIENT_SECRET,
and CLIO_ENCRYPTION_KEY in the shell that starts Claude Code. If Claude Code
isn't picking it up:
claude /mcp
If it's red, check claude --debug output for the failing command. Common
causes: env vars missing in the shell that launched Claude Code, no network on
first run (npx fetches + builds the server once), or stale tokens (delete
tokens.enc and re-authenticate).
Azure path (only if asked)
If the user wants firm-wide hosted deployment, point them at
docs/deployment-azure.md. The
plugin's local stdio config is not what they want for Azure — they'll
need the HTTP transport with bearer auth, and Claude Code's --mcp-config
URL flag.
One behavioral difference worth telling them: sessions on the remote OAuth
connector carry a scope tier the user picks on the consent page —
clio:read, clio:write, or clio:destructive — and tools outside the
granted tier are not listed. Local stdio mode has full access (destructive
tools still gated by CLIO_ALLOW_DESTRUCTIVE, default false).
After it works
Suggest a quick test prompt:
"Who am I in Clio?"
That fires clio_who_am_i, confirms the OAuth token, and prints the user's
firm + email. If that returns the right user, setup is done.
