Set up Mercator

Connect Mercator in your agent, authorize it, and 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

1. Run the installer in your computer's terminal:

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

2. Select the installed agents you want to connect.

3. Complete authorization in your agent, then run your first job.

• Claude Desktop, Claude web, or ChatGPT: use Agent setup.
• Updates and installer options: see the CLI reference.
• New wallet session: sign in and approve payment permission in one Tempo Wallet approval.
• Existing wallet session: approve access for the same account wallet.

Agent setup

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

Local agents

Run the installer in the terminal where your agent runs:

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

Activate after installation

1. Load the installed configuration using your client's action below.
2. Complete the client's OAuth flow. Mercator requests mercator:tools for /mcp/auth.
3. Call search_services and get_connection_status in that client.

• Setup lists each client under Client readiness with its activation and authorization steps. A written registration stays "authorization pending" until you authorize in the client.
• mercator refresh updates managed files but does not restart clients.
• mercator doctor verifies the separate CLI connection.

For immediate terminal access, use the CLI MCP client.

mercator setup --client claude

mercator setup --client codex

mercator setup --client cursor

mercator setup --client vscode

mercator setup --client gemini

mercator setup --client cline

mercator setup --client continue

mercator setup --client windsurf

mercator setup --client grok

mercator setup --client hermes

mercator setup --client kiro

mercator setup --client lmstudio

mercator setup --client muse

mercator setup --client openclaw

mercator setup --client zed

Verify the connection

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. The status response includes the wallet address and public access-key address.
• For a REST client, call GET /v1/connection/status with its /mcp/auth OAuth bearer token. Missing, invalid, or revoked tokens return 401; the response is never cached.
• 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 a localhost callback, Mercator shows a completion page after approval. Select Return to your client when the browser is on the same device. If you are connecting on another device, copy the one-time link and return it to the same client connection. With mercator login, paste the link or code at the terminal prompt. Keep it private. 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

Install, configure, and call Mercator from your terminal.

• 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 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/plugins 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

Use the CLI as an MCP client

1. Run mercator login and complete browser authorization.
2. Inspect live tools with mercator tools.
3. Call a tool with mercator call:

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

• mercator setup reuses existing CLI credentials to check discovery and spending capacity. Interactive mercator setup --login signs in when needed.
• The CLI connection is named mercator cli; agent clients authorize separately.
• Setup authorizes the CLI only with --login; CLI login creates a separate access key that can spend.
• --yes, non-interactive setup, and mercator refresh never launch login.
• Cancelled login leaves integrations installed; retry with mercator setup --login.
• Choose wallet limits in the browser authorization flow. Login and doctor create no paid jobs.
• If approval happens on another device, copy the completion link and paste it into the waiting mercator login prompt. The CLI also accepts the code from that link.
• 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

The bootstrap installer accepts these environment overrides:

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 plugin marketplace add tempoxyz/plugins --ref main
codex plugin add mercator@tempo

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

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

Manual installation

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

1. Run mercator setup --manual.
2. Add https://mercator.sh/mcp/auth using Streamable HTTP.
3. Complete OAuth in the client; use the registration instructions if it requires a client ID.
4. Verify with search_services and get_connection_status there.

• Registration or a 401 challenge does not prove payment readiness.
• mercator doctor cannot read client-managed credentials.

You can register the remote MCP endpoint directly in a supported harness:

• For harnesses with tool search, such as Claude Code and Codex, append ?tools=all to the URL to list every catalog service as its own tool. Omit it for clients that load every tool into context.

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

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

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

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

openclaw mcp set mercator '{"url":"https://mercator.sh/mcp/auth","transport":"streamable-http","auth":"oauth"}'
openclaw mcp login mercator

hermes mcp add mercator --url https://mercator.sh/mcp

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

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

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

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