---
name: mercator-setup
description: Install, connect, or troubleshoot Mercator in agent clients. Use for plugin setup, OAuth authorization, missing tools, connection diagnostics, and wallet funding readiness. For discovery and paid API execution on a working connection, use mercator.
license: MIT
---

# Mercator setup

Connect the user's chosen client and verify readiness with free checks. Setup does not require a
paid job or a local payment wallet.

## Connect or repair

- Identify the user's app and mode first; ask if unclear. Do not infer local terminal access
  from the agent's ability to run commands in a sandbox.
- **Claude Desktop chat or claude.ai:** direct the user to **Customize → Connectors → Add custom
  connector**, name it **Mercator**, and enter `https://mercator.sh/mcp/auth`. The user completes
  connection and authorization. Do not run the installer in the chat sandbox. `--client claude`
  means Claude Code, not Desktop chat.
- **Plugin installed:** inspect native MCP status and complete the client's **Authorize** action.
  Reload the plugin or start a new session if tools are missing; avoid installing a duplicate.
- **Local client:** run `mercator status`, then `mercator setup` to install or repair. Consult
  `mercator setup --help` and honor the user's client choice with `--client`.
- **CLI absent:** install and start setup with the canonical command below. Append setup arguments
  with `sh -s -- --client <client>` when the user selected a client.
- **Managed or cloud host:** use native plugin and OAuth controls. A CLI inside an agent container
  does not configure the user's desktop.
- **Other MCP client:** run `mercator setup --manual` for current connection instructions.

```bash
curl -fsSL https://mercator.sh/install.sh | sh
```

## Verify and recover

- Run `mercator doctor` when available and follow its diagnostics. Use targeted
  `mercator setup --client <client> --verbose` for persistent setup failures.
- On the connected server, inspect live tool descriptions and call `search_services` and
  `get_connection_status` for free discovery and payment-readiness checks. Follow their returned
  next steps. An OAuth challenge alone does not prove authorization or paid readiness.
- Report verified readiness and remaining user actions. Never create a paid job as a connection test.
- The user chooses wallet access limits, expiry, and funding. Never request private keys, copy tokens
  into chat, or install a local payment wallet to repair hosted OAuth.
- Exclude credentials, OAuth codes, payment material, and raw provider data from shared diagnostics.