# Set up Mercator

Install or register Mercator in the app where you want to use it, complete that app’s authorization, then verify with a free search. Setup does not require a paid job. Report connection and payment readiness separately.

If you are an agent and the user’s app or mode is unclear, ask before choosing a setup path. Installing a CLI in a disposable chat sandbox does not configure the user’s desktop.

<nav className="setup-jump-links" aria-label="Setup sections">
  <a href="/setup#installation">Install</a>
  <a href="/setup#agent-setup">Choose your agent</a>
  <a href="/setup#verify-the-connection">Verify</a>
  <a href="/setup#browser-handoff">Browser handoff</a>
  <a href="/setup#manual-installation">Manual configuration</a>
</nav>

<a href="/setup.md" data-v="true" data-v-link="true">Read as Markdown</a> · [Full documentation](/docs)

## Installation

<span aria-hidden="true" id="install-the-cli" />

Run this in your computer's terminal. Setup detects installed agents and lets you choose which
ones to connect:

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

Complete authorization in your agent, then [run your first job](/docs#run-your-first-job).
For Claude Desktop, Claude web, ChatGPT, or individual agent instructions, see
[Agent setup](#agent-setup). For setup options and updates, see the [CLI reference](#cli-reference).

During authorization, new sessions sign in and approve payment permission in one Tempo Wallet
approval. Existing sessions approve access for the same account wallet.

## Agent setup

Choose your app below for its exact registration and authorization steps.

| Where you use your agent | Setup path |
| --- | --- |
| Claude Code, Codex, Cursor, or another installed client | [Local agents](#local-agents) |
| Claude Desktop chat, Claude web, or Cowork | [Claude connectors](#claude-desktop-chat-and-claude-web) |
| ChatGPT on the web | [Developer-mode app](#chatgpt-web) |
| Cloud agent, team-managed host, or remote machine | [Managed and remote environments](#managed-and-remote-environments) |
| Another MCP client | [Manual installation](#manual-installation) |

### Local agents

Run this in your computer's terminal. Setup detects installed clients and lets you select which
ones to configure:

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

To configure just one client during installation, pass its ID after `sh -s --`:

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

If Mercator is already installed, use the command for your client below. Run project-scoped
setup from the project you use in that agent. Commands register Mercator; authorization is a
separate step.

### Activate after installation

Installation writes configuration; the running agent must load it before tools are available.
`mercator refresh` updates managed files but does not restart your client.

| Client / change | Next step |
| --- | --- |
| Claude Code terminal plugin | Run `/reload-plugins` in the current session. If it warns about the prompt cache, run `/reload-plugins --force`. Restart Claude Code if unsupported. |
| Claude Code without an interactive terminal | Start a new session to load plugin MCP changes. |
| Codex plugin | Check plugin/MCP status first: recent versions support live refresh. If tools remain missing, fully quit and reopen the desktop app, or exit and resume the CLI. |
| Grok plugin | Restart Grok after a plugin refresh when setup requests it. |
| Standalone MCP configuration | If Mercator is missing, restart the client, then authorize. Plugin reload may not load standalone registrations. |
| Codex `AGENTS.md` guidance | Start a new session to load changed instructions. |

After activation, complete the client's OAuth flow and call `search_services` and
`get_connection_status` there. `mercator doctor` verifies the separate CLI connection.
For immediate terminal access, use `mercator login`, `mercator tools`, and `mercator call`;
this does not activate tools in an already-running agent.

:::details[Claude Code]
User MCP registration and Mercator plugin.

```bash
mercator setup --client claude
```

In Claude Code, run `/mcp`, select Mercator, and complete browser authorization.
See [Claude Code MCP](https://code.claude.com/docs/en/mcp#authenticate-with-remote-mcp-servers).
:::

:::details[Codex]
Local Codex MCP registration; requires the Codex CLI on PATH.

```bash
mercator setup --client codex
```

Run `codex mcp login mercator` to authorize. See [Codex MCP configuration](https://learn.chatgpt.com/docs/extend/mcp?surface=cli).
:::

:::details[Cursor]
User MCP configuration in `~/.cursor/mcp.json`.

```bash
mercator setup --client cursor
```

Open Cursor's **Customize** page, find Mercator under MCP servers, and complete its OAuth
sign-in. See [Cursor MCP](https://cursor.com/docs/mcp).
:::

:::details[Visual Studio Code]
MCP registration through the `code` command.

```bash
mercator setup --client vscode
```

Run **MCP: List Servers** from the Command Palette, select Mercator, and start it. Complete
any trust and sign-in prompts, then enable its tools in agent chat. See
[VS Code MCP](https://code.visualstudio.com/docs/agent-customization/mcp-servers).
:::

:::details[Gemini CLI]
User MCP registration.

```bash
mercator setup --client gemini
```

In Gemini CLI, run `/mcp auth mercator` and complete browser authorization.
See [Gemini MCP authentication](https://geminicli.com/docs/tools/mcp-server/#managing-oauth-authentication).
:::

:::details[Cline]
Use Cline's native setup so the server is saved in the configuration your client reads:

```bash
cline mcp
```

Choose **Add server**, name it `mercator`, select **Streamable HTTP**, and enter
`https://mercator.sh/mcp/auth`. Complete browser authorization; use **Authorize OAuth** to retry.

In the IDE extension, use **MCP Servers** > **Remote Servers** instead. See
[Cline MCP configuration](https://docs.cline.bot/mcp/mcp-overview).

`mercator setup --client cline` currently writes project `.cline/mcp.json`; Cline's documented
CLI location is `~/.cline/mcp.json`, and the extension manages its own configuration. Use the
native setup above until the installer targets those locations.
:::

:::details[Continue]
Project `.continue/mcpServers/mercator.json`.

```bash
mercator setup --client continue
```

Use **Agent mode** in Continue and complete the OAuth sign-in for Mercator.
See [Continue MCP](https://docs.continue.dev/customize/deep-dives/mcp).
:::

:::details[Windsurf]
User `~/.codeium/windsurf/mcp_config.json`.

```bash
mercator setup --client windsurf
```

Open **MCPs** in the Cascade panel, select Mercator, and complete OAuth authorization.
See [Cascade MCP](https://docs.windsurf.com/windsurf/cascade/mcp).
:::

:::details[Grok]
User MCP registration and Mercator plugin.

```bash
mercator setup --client grok
```

Open `/mcps`, select Mercator, and press `i` to authorize.
See [Grok MCP](https://docs.x.ai/build/features/mcp-servers).
:::

:::details[Hermes]
Native MPP integration at `/mcp`, not hosted OAuth.

```bash
mercator setup --client hermes
```

The installer selects `/mcp` and sets up the `hermes-mpp` payment plugin. Complete any
remaining plugin and wallet steps it prints before paid use. Native MPP requires quote approval
or an explicit spending budget. See [Hermes MCP commands](https://hermes-agent.nousresearch.com/docs/reference/cli-commands/#hermes-mcp).
:::

:::details[Kiro]
User `~/.kiro/settings/mcp.json`.

```bash
mercator setup --client kiro
```

Connect to Mercator from Kiro's MCP controls and complete the browser authorization it opens.
See [Kiro MCP authentication](https://kiro.dev/docs/mcp/configuration/#oauth-authentication).
:::

:::details[LM Studio]
User `~/.lmstudio/mcp.json`.

```bash
mercator setup --client lmstudio
```

Enable Mercator in LM Studio and complete the browser authorization it opens.
See [LM Studio MCP authentication](https://lmstudio.ai/docs/integrations/mcp-remote).
:::

:::details[Muse Code]
XDG Muse settings, normally `~/.config/muse/settings.json`.

```bash
mercator setup --client muse
```

Run `muse mcp login mercator` to authorize.
:::

:::details[OpenClaw]
Native MCP configuration with OAuth enabled.

```bash
mercator setup --client openclaw
```

Interactive setup starts login; otherwise run `openclaw mcp login mercator`.
See [OpenClaw OAuth](https://docs.openclaw.ai/cli/mcp/transports#oauth-workflow).
:::

:::details[Zed]
`context_servers` in Zed user settings.

```bash
mercator setup --client zed
```

Open **Settings** > **AI** > **MCP Servers** and complete Mercator's OAuth prompt. Use it from
Zed's Agent Panel. See [Zed MCP](https://zed.dev/docs/ai/mcp).
:::

<span aria-hidden="true" id="claude-desktop-chat-and-claude-web" />

:::details[Claude Desktop chat and Claude web]
1. Open **Customize** > **Connectors**, click **+**, then **Add custom connector** in Claude Desktop
   or claude.ai.
2. Name it **Mercator** and enter `https://mercator.sh/mcp/auth`.
3. Complete Claude's connection and authorization flow, then check the free `search_services`
   and `get_connection_status` tools in your conversation.

This uses Claude's remote connector; no terminal installation is required. The user completes
authorization and chooses wallet limits. See [Claude's connector guide](https://support.claude.com/en/articles/11176164-use-connectors-to-extend-claude-s-capabilities)
if your organization manages connector access.

Cowork can use the same remote connector. If the connector controls are unavailable, check the
host's current account and organization requirements; installing a CLI inside the conversation
does not enable them.
:::

<span aria-hidden="true" id="chatgpt-web" />

:::details[ChatGPT web]
Where your account and workspace permit custom apps:

1. Enable **Developer mode** in **Settings** > **Security and login**.
2. Open **Plugins**, use the **+** button, and create a developer-mode app named **Mercator**.
3. Enter `https://mercator.sh/mcp/auth`, choose OAuth, and complete authorization. If prompted
   for a registration method, use dynamic client registration (DCR).
4. Select the app from the conversation's **Developer mode** tools, then [verify the connection](#verify-the-connection).

Follow [OpenAI's developer-mode guide](https://developers.openai.com/api/docs/guides/developer-mode)
for current availability and controls. A local Codex registration or `mercator login` does not
authorize this ChatGPT connection. Do not run the installer in ChatGPT's code-execution sandbox.
:::

<span aria-hidden="true" id="managed-and-remote-environments" />

:::details[Managed and remote environments]
* **Cloud or team-managed agents:** use the host's native plugin or connector controls. Where it
  supports remote MCP with OAuth, add `https://mercator.sh/mcp/auth` using Streamable HTTP and
  complete authorization. An administrator may need to enable the integration first.
* **SSH, containers, and remote development:** run setup where the intended agent client runs.
  Configuration written there does not configure a separate desktop app. If the browser cannot
  reach the client's loopback callback, use Mercator's [browser handoff](/setup#browser-handoff)
  and copy the completion link back to the same client. Use its documented code input or port
  forwarding if it cannot accept the full link. Hosted and app-link callbacks return normally.
* **No connector controls or compatible OAuth support:** use a supported client instead. Do not
  repeatedly run the installer in a disposable sandbox or paste tokens or private keys into chat.
* **Unclear app or mode:** identify it before choosing a setup path. Claude Code, Claude Desktop
  chat, local Codex, and ChatGPT web do not share one installation or authorization flow.
:::

### Verify the connection

Then verify the connection in that client. See [manual installation](#manual-installation)
for direct MCP commands and configuration examples without installer-managed setup.

In the client you connected, ask:

```text
Use Mercator to search for web research services, then check my connection status.
Do not create a paid job.
```

* Confirm the agent can call `search_services` and `get_connection_status`; both checks are free.
* Follow any returned authorization or funding steps. Registration, a browser account login,
  or an HTTP 401 challenge alone does not prove the client's connection is ready.
* **Hosted OAuth:** choose wallet limits and expiry during authorization. Zero limits allow
  connecting without spending authority; a successful connection does not imply paid readiness.
* **Hermes/native MPP:** `get_connection_status` reports `mcp_challenge` without wallet balances.
  Check the native payment plugin and wallet separately; this response does not verify spending readiness.
* Keep each client's authorization in that client. CLI login and `mercator doctor` cannot verify
  credentials owned by another agent host.

## Connection and payment readiness

Check the connected client's payment capacity before submitting a paid job. Use the browser handoff
steps when authorization opens inside another app or remote machine.

### Check spending readiness

Call `get_connection_status` in your authorized client. Its `readiness` field separates
OAuth authorization, wallet binding, funding, spend policy, and paid-execution capacity.
Each token reports its balance, remaining allowance, and `spendableNow` when known.
A grant ceiling is not a balance; unavailable values are not zero. Compare the quoted
amount with that token's capacity before submitting a job.

Hosted OAuth allows paid jobs within your signed limits and explicit budget without
per-job confirmation. Legacy payment challenges require approval or a sufficient budget.
Free discovery and quotes remain available when unfunded. Use [Account](/account) to fund
or manage access, then repeat the free check. `mercator doctor` checks the CLI connection;
it cannot verify credentials held by another client.

### Browser handoff

If onboarding opens inside an app that cannot use your passkey, expand **Continue in another
browser** and copy the browser sign-in link. Paste it into the browser where you keep your
passkeys and GitHub session. Approve the connection there. Keep the link private.

The link starts a fresh browser-bound authorization for the same client request. Copying
an `/account?authorization=...` URL does not work in another browser because its cookie
stays in the original browser. A website cannot force an external browser to open.

For Instinct on a phone or another client with an unreachable localhost callback, the
handoff selects **Copy a completion link** on the approval screen. After approval, copy
the one-time completion link from Mercator and return it to the same client connection
that started authorization. If you opened the approval directly, select that option
yourself. Keep the link private; use a dedicated callback or code input when available.
Restart authorization from the client if the link expires or the page is lost.

Other callback paths:

* Hosted and app-link callbacks, including clients that return to their own browser,
  continue automatically.
* OpenClaw accepts the code from the completion link with its documented
  `openclaw mcp login mercator --code CODE` fallback.
* For a localhost callback over SSH, you can instead forward the exact port printed by
  the client: `ssh -L PORT:127.0.0.1:PORT USER@AGENT_HOST`. Keep the tunnel open while
  completing sign-in.

After returning, call the free `search_services` and `get_connection_status` tools in the
original client. Opening the link or signing into the website alone does not verify the
client connection. GitHub MACH claims run in the selected browser's Account session.

## CLI reference

Setup options, updates, and manual registration. For the installer, see [Installation](#installation).

The installer downloads a checksum-verified standalone executable; Node.js and Bun are not
required. It updates the active shell's PATH profile when needed. A failed reinstall keeps using
the existing executable.

### Configuration

Pass setup arguments after `sh -s --`:

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

* **Codex/ChatGPT desktop:** Installs one local plugin by default. ChatGPT web uses the
  separate [developer-mode app setup](#chatgpt-web).
* **Claude Code and Grok CLI:** Registers the public `tempoxyz/docs` marketplace and installs its Mercator plugin.
* **No detected client:** Installs the local desktop plugin when enabled. Install a supported
  client and rerun setup, or use `mercator setup --manual` for other MCP clients.
* **Cloud/team marketplaces:** Managed by the host.

#### CLI commands

| Command | Purpose |
| --- | --- |
| `mercator login` | Authorize the CLI through browser OAuth. |
| `mercator logout` | Remove local CLI credentials. |
| `mercator tools` | List live MCP tools and schemas. |
| `mercator call <tool> --input '{…}'` | Invoke an MCP tool. |
| `mercator setup` | Connect Mercator to installed agent clients. |
| `mercator status` | Show client registrations and connection status. |
| `mercator account` | Manage hosted wallet access, limits, funding, and revocation. |
| `mercator refresh` | Update and refresh existing managed integrations using saved setup choices. |
| `mercator doctor` | Check MCP transport, discovery, and local integrations. |
| `mercator uninstall` | Remove MCP registrations, the plugin, and managed guidance. |
| `mercator local` | Use a separate local wallet and submit REST jobs. |

### Use the CLI as an MCP client

Interactive `mercator setup` signs in the CLI through browser OAuth when needed, then checks
discovery and spending capacity automatically. Existing CLI credentials are reused. This connection
is named **mercator cli**; agent clients authorize separately.

`--yes`, non-interactive setup, and `mercator refresh` never launch login. If login is cancelled,
installed integrations remain in place; rerun `mercator setup` in an interactive terminal.

To sign in explicitly, then discover and invoke live tools:

```sh
mercator login
mercator tools
mercator call get_connection_status
mercator call search_services --input '{"query":"web research"}'
mercator doctor
```

* Choose wallet limits in the browser authorization flow. Login and doctor create no paid jobs.
* `tools` returns current tool descriptions and input schemas. `call` accepts a JSON object and
  returns the MCP result; tool errors exit nonzero. Paid tools use the connection's approved limits.
* Credentials stay in endpoint-scoped, owner-only files under `~/.local/share/mercator/oauth/`.
  Expiring bearers refresh automatically. Other agent clients retain their own authorization.
* The Tempo access key remains valid until revoked by default. Revoke the connection in
  [Account](/account) to disable OAuth first, then ask Tempo Wallet to revoke the on-chain key.
  For a key that has not yet been published, Account returns its signed public authorization so
  Wallet can authorize and revoke it in one transaction.
* `mercator logout` removes local CLI credentials. Revoke **mercator cli** in [Account](/account)
  to revoke its wallet access.

### Setup options

| Option | Behavior |
| --- | --- |
| `--client <name>` | Configure one client; repeat for several. IDs: `claude`, `cline`, `codex`, `continue`, `cursor`, `gemini`, `grok`, `hermes`, `kiro`, `lmstudio`, `muse`, `openclaw`, `vscode`, `windsurf`, and `zed`. |
| `--url <url>` | Use another Mercator MCP endpoint, including a local development endpoint. |
| `--dry-run` | Preview configuration changes without writing them. |
| `--yes` | Select every detected client unless `--client` is specified, and apply without setup prompts or installer-initiated login. Existing CLI credentials are reused. |
| `--verbose` | Keep progress output and append detailed setup diagnostics. |
| `--manual` | Print MCP/OAuth connection instructions without configuring integrations. Incompatible with `--client`, `--force`, and `--remove-agents`. |
| `--force` | Recreate MCP registrations; complete native OAuth in the client. |
| `--plugin` / `--no-plugin` | Enable or disable the local desktop plugin. Enabled by default. |
| `--skill` / `--no-skill` | Include or omit the Mercator skill inside the plugin. Included by default. |
| `--agents` / `--no-agents` | Enable or disable managed [Codex `AGENTS.md` guidance](https://learn.chatgpt.com/docs/agent-configuration/agents-md). Enabled by default. |
| `--remove-agents` | Remove only managed Codex guidance and stop; incompatible with `--force` and `--no-agents`. |

The bootstrap installer accepts these environment overrides:

| Variable | Behavior |
| --- | --- |
| `MERCATOR_BIN_DIR` | Set the executable directory; highest precedence. Relative paths are resolved before installation. |
| `MERCATOR_INSTALL_DIR` | Set the executable directory when `MERCATOR_BIN_DIR` is unset. |
| `INSTALL_DIR` | Generic fallback when neither Mercator-specific directory is set. |
| `MERCATOR_INSTALLER_URL` | Download a specific trusted HTTPS release installer. |
| `MERCATOR_NO_MODIFY_PATH=true` | Leave shell profiles unchanged and print the PATH command instead. |
| `MERCATOR_SKIP_SETUP=true` | Install the CLI without running setup. Run `mercator setup` later. |

### Install the plugin from the Tempo marketplace

The installer bootstraps the Mercator plugin for detected supported clients. To install it directly,
add the public Tempo marketplace and select the `mercator@tempo` plugin:

:::details[Codex]
```bash
codex plugin marketplace add tempoxyz/docs --ref main
codex plugin add mercator@tempo
```
:::

:::details[Claude Code]
```bash
claude plugin marketplace add tempoxyz/docs
claude plugin install mercator@tempo --scope user
```
:::

:::details[Grok]
```bash
grok plugin marketplace add tempoxyz/docs
grok plugin install mercator@tempo
```
:::

:::note[Grok CLI authorization]
Grok CLI handles MCP OAuth natively. Run `mercator setup --client grok`, then open `/mcps`,
select Mercator, and press `i` to authorize. Grok stores and refreshes its own OAuth credentials.
Setup migrates older user registrations that contain a static Authorization header.

For SSH sessions, forward Grok's printed loopback port over SSH. This integration does not
document a manual callback input for Grok.
:::

### Manual installation

Merge configuration examples into the existing file; preserve other servers and settings.

For other MCP clients, run `mercator setup --manual`. Add `https://mercator.sh/mcp/auth`
using Streamable HTTP and complete OAuth in that client; see the
[registration instructions](https://mercator.sh/auth.md) if it requires a client ID.
After connecting, verify with the free `search_services` and `get_connection_status` tools in your client.
A successful registration or a 401 challenge is not proof of payment readiness. `mercator doctor`
cannot read credentials managed by the client.

You can register the remote [MCP](https://modelcontextprotocol.io/docs/getting-started/intro) endpoint directly in a supported harness:

:::details[Codex]
```bash
codex mcp add mercator --url https://mercator.sh/mcp/auth --oauth-client-registration dcr
```
:::

:::details[Claude Code]
```bash
claude mcp add --scope user --transport http mercator https://mercator.sh/mcp/auth
```
:::

:::details[Gemini CLI]
```bash
gemini mcp add mercator https://mercator.sh/mcp/auth --transport http --scope user
```
:::

:::details[VS Code]
```bash
code --add-mcp '{"name":"mercator","type":"http","url":"https://mercator.sh/mcp/auth"}'
```
:::

:::details[OpenClaw]
```bash
openclaw mcp set mercator '{"url":"https://mercator.sh/mcp/auth","transport":"streamable-http","auth":"oauth"}'
openclaw mcp login mercator
```

If the browser cannot reach OpenClaw's loopback callback, use its
[documented remote-browser fallback](https://docs.openclaw.ai/cli/mcp/transports#oauth-workflow).
Do not paste authorization codes into chat.
:::

:::details[Hermes]
```bash
hermes mcp add mercator --url https://mercator.sh/mcp
```

This registers the MCP server only. Paid use also requires the native MPP plugin and wallet;
`mercator setup --client hermes` checks the plugin and prints any remaining steps.
:::

:::details[Kiro]
Add to `~/.kiro/settings/mcp.json`:

```json
{"mcpServers":{"mercator":{"url":"https://mercator.sh/mcp/auth"}}}
```
:::

:::details[LM Studio]
Add to `~/.lmstudio/mcp.json`:

```json
{"mcpServers":{"mercator":{"url":"https://mercator.sh/mcp/auth"}}}
```
:::

:::details[Muse Code]
Bootstrap only Muse's MCP configuration, then authorize with Muse:

```bash
mercator setup --client muse --no-plugin --no-agents
muse mcp login mercator
```

Setup preserves other entries in `~/.config/muse/settings.json` (or the `XDG_CONFIG_HOME`
equivalent), initializes `schema_version: 1`, and adds Mercator using `transport: "streamable_http"`.
It uses an existing `mcpServers` map when present, otherwise `mcp_servers`. Start a new Muse session
and check `/mcp`. Configuration does not complete OAuth; Muse stores and refreshes the credentials.
This integration does not require Muse's experimental plugin commands.
:::

:::details[Zed]
Add `mercator` under `context_servers` in the Zed user settings file:

```json
{"context_servers":{"mercator":{"url":"https://mercator.sh/mcp/auth"}}}
```
:::

Manual registration saves the server configuration. Complete authorization and
[verify the connection](#verify-the-connection) in that client. OAuth-capable clients open Account
when authorization is required. Run `mercator account` to manage wallet access, limits, funding, and revocation.