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.

Read as Markdown · Full documentation

Installation

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

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

Complete authorization in your agent, then run your first job. For Claude Desktop, Claude web, ChatGPT, or individual agent instructions, see Agent setup. For setup options and updates, see the 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
Claude Desktop chat, Claude web, or Cowork	Claude connectors
ChatGPT on the web	Developer-mode app
Cloud agent, team-managed host, or remote machine	Managed and remote environments
Another MCP client	Manual installation

Local agents

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

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

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

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.

Claude Code

User MCP registration and Mercator plugin.

mercator setup --client claude

In Claude Code, run /mcp, select Mercator, and complete browser authorization. See Claude Code MCP.

Codex

Local Codex MCP registration; requires the Codex CLI on PATH.

mercator setup --client codex

Run codex mcp login mercator to authorize. See Codex MCP configuration.

Cursor

User MCP configuration in ~/.cursor/mcp.json.

mercator setup --client cursor

Open Cursor's Customize page, find Mercator under MCP servers, and complete its OAuth sign-in. See Cursor MCP.

Visual Studio Code

MCP registration through the code command.

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.

Gemini CLI

User MCP registration.

mercator setup --client gemini

In Gemini CLI, run /mcp auth mercator and complete browser authorization. See Gemini MCP authentication.

Cline

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

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.

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.

Continue

Project .continue/mcpServers/mercator.json.

mercator setup --client continue

Use Agent mode in Continue and complete the OAuth sign-in for Mercator. See Continue MCP.

Windsurf

User ~/.codeium/windsurf/mcp_config.json.

mercator setup --client windsurf

Open MCPs in the Cascade panel, select Mercator, and complete OAuth authorization. See Cascade MCP.

Grok

User MCP registration and Mercator plugin.

mercator setup --client grok

Open /mcps, select Mercator, and press i to authorize. See Grok MCP.

Hermes

Native MPP integration at /mcp, not hosted OAuth.

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.

Kiro

User ~/.kiro/settings/mcp.json.

mercator setup --client kiro

Connect to Mercator from Kiro's MCP controls and complete the browser authorization it opens. See Kiro MCP authentication.

LM Studio

User ~/.lmstudio/mcp.json.

mercator setup --client lmstudio

Enable Mercator in LM Studio and complete the browser authorization it opens. See LM Studio MCP authentication.

Muse Code

XDG Muse settings, normally ~/.config/muse/settings.json.

mercator setup --client muse

Run muse mcp login mercator to authorize.

OpenClaw

Native MCP configuration with OAuth enabled.

mercator setup --client openclaw

Interactive setup starts login; otherwise run openclaw mcp login mercator. See OpenClaw OAuth.

Zed

context_servers in Zed user settings.

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.

Claude Desktop chat and Claude web

Open Customize > Connectors, click +, then Add custom connector in Claude Desktop or claude.ai.
Name it Mercator and enter https://mercator.sh/mcp/auth.
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 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.

ChatGPT web

Where your account and workspace permit custom apps:

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

Follow OpenAI's developer-mode guide 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.

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 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 for direct MCP commands and configuration examples without installer-managed setup.

In the client you connected, ask:

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 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.

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 --:

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.
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:

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 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 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. 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:

Codex

codex plugin marketplace add tempoxyz/docs --ref main
codex plugin add mercator@tempo

Claude Code

claude plugin marketplace add tempoxyz/docs
claude plugin install mercator@tempo --scope user

Grok

grok plugin marketplace add tempoxyz/docs
grok plugin install mercator@tempo

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 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 endpoint directly in a supported harness:

Codex

codex mcp add mercator --url https://mercator.sh/mcp/auth --oauth-client-registration dcr

Claude Code

claude mcp add --scope user --transport http mercator https://mercator.sh/mcp/auth

Gemini CLI

gemini mcp add mercator https://mercator.sh/mcp/auth --transport http --scope user

VS Code

code --add-mcp '{"name":"mercator","type":"http","url":"https://mercator.sh/mcp/auth"}'

OpenClaw

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. Do not paste authorization codes into chat.

Hermes

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.

Kiro

Add to ~/.kiro/settings/mcp.json:

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

LM Studio

Add to ~/.lmstudio/mcp.json:

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

Muse Code

Bootstrap only Muse's MCP configuration, then authorize with Muse:

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.

Zed

Add mercator under context_servers in the Zed user settings file:

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

Manual registration saves the server configuration. Complete authorization and 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.