Mercator documentation

Mercator gives agents one interface to:

• Find tools for an open-ended workflow.
• Quote an immutable plan of one or more tool calls.
• Pay for and run the plan as one durable job.

Downstream services remain independently operated and use open payment protocols such as MPP and x402.

AgentIntent + budget

Mercator

01Search the web

02Enrich records

03Compose result

Downstream services

ExaWeb search

ParallelWeb research

OpenAIModel inference

Choose a path

• New to Mercator: Install Mercator, then run your first job.
• Connecting another client: Find your app in Agent setup.
• Building an integration: Start with the API and key concepts.
• Managing payments: Read costs and payment and MACH.
• Operating a service: See Mercator for service owners.

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.

Run your first job

After setup, authorize Mercator and fund your wallet in Account. Then give your agent this prompt:

Use Mercator to find NVIDIA's latest 10-Q and 8-K via SEC submissions. Return official links,
dates, and one-sentence summaries.

For more ideas, ask for get_suggested_queries. The same catalog appears under Try Mercator after CLI setup:

The agent should:

1. Call search_services with the complete outcome.
2. Build the smallest valid plan from the returned endpoint.
3. Call quote_plan; search, inspection, and quoting are free.
4. Call create_job once with a stable idempotency key and the quoted total as approved_total.
5. Poll get_job until it returns a terminal result.

Expected outcome: the agent returns both filings, dates, official sources, and summaries. If the job remains pending, it should return the job ID so polling can resume without another purchase.

Paid execution uses the limits approved during browser authorization. An explicit budget in your prompt is an additional limit. For native MPP clients such as Hermes, configure the client's payment wallet and provide an explicit budget or approve the quote before paying.

API

Mercator offers REST and MCP interfaces:

• REST: Read the live OpenAPI specification, which includes the generated x-mercator-mcp tool contracts.
• MCP: Connect a Streamable HTTP client to https://mercator.sh/mcp/auth.

Both interfaces share discovery, quoting, jobs, and accounting. Use MCP for agent workflows or REST for direct application integration.

Service discovery

• API catalog
• Agent discovery document
• MCP server card
• Agent skills index
• OAuth setup guide
• OAuth protected-resource metadata
• WebMCP: Read-only service search and description tools on the homepage.

To require a specific provider, pass its service ID and serviceMode=require to REST search:

curl -G 'https://mercator.sh/v1/services/search' \
  --data-urlencode 'query=search the web' \
  --data-urlencode 'serviceId=exa' \
  --data-urlencode 'serviceMode=require'

In MCP, pass service_ids: ["exa"] and service_mode: "require" to search_services. Use prefer to retain relevant fallback services. Add more IDs to either list to select more than one provider. Submitted plans name the exact service and endpoint for each node.

MCP tools

Use this table to find the REST route or MCP tool for each operation.

Run a REST workflow

Use the live OpenAPI document for complete schemas. This workflow requires a payment-capable client with an existing local Mercator wallet for submission. Replace each {{PLACEHOLDER}} with the returned endpoint, quote, or job value before running its command.

1. Search for an endpoint that satisfies the complete outcome:

   curl -G 'https://mercator.sh/v1/services/search' \
     --data-urlencode 'query=find the latest official NVIDIA SEC filing' \
     --data-urlencode 'resolution=live' \
     --data-urlencode 'limit=5'

2. Inspect the returned endpoint's input schema. Save plan.json with its exact serviceId, method, path, and schema-valid input:

   curl 'https://mercator.sh/v1/services/{{SERVICE_ID}}'

   {
     "nodes": [
       {
         "id": "filing",
         "serviceId": "{{SERVICE_ID}}",
         "method": "{{METHOD}}",
         "path": "{{PATH}}",
         "input": { "query": "latest official NVIDIA SEC filing" },
         "dependsOn": []
       }
     ]
   }

3. Quote the plan without spending money:

   curl 'https://mercator.sh/v1/quote' \
     --header 'content-type: application/json' \
     --data-binary @plan.json

4. Save job.json with the unchanged plan and a new 8–200 character idempotencyKey. Submit it with the quoted totalAmount as your spending cap. The CLI handles the MPP payment challenge using your existing local wallet. Persist the returned jobId.

   An empty request may return a zero-value discovery challenge. It cannot submit a job; retrying it with a payment credential returns 400. Use the quoted plan to obtain the actual charge.

   {
     "idempotencyKey": "{{IDEMPOTENCY_KEY}}",
     "plan": {
       "nodes": [
         {
           "id": "filing",
           "serviceId": "{{SERVICE_ID}}",
           "method": "{{METHOD}}",
           "path": "{{PATH}}",
           "input": { "query": "latest official NVIDIA SEC filing" },
           "dependsOn": []
         }
       ]
     }
   }

   mercator local submit \
     --url 'https://mercator.sh/v1/jobs' \
     --max-spend '{{QUOTED_TOTAL}}' \
     --body "$(cat job.json)"

   If submission times out, retry the unchanged body with the same key. A new key can create a second paid job. Never reuse a key with a changed plan.

5. Poll the same job while status is pending or running:

   curl 'https://mercator.sh/v1/jobs/{{JOB_ID}}'

Terminal statuses are succeeded, partially_succeeded, and failed; each returns cached outputs, summary: {succeeded, failed, skipped}, and a failures array with node IDs, services, and reasons. Partial success retains successful outputs: present those first, then explain failures. An interrupted job keeps its state; continue polling its ID. Free calls retry transient failures up to three times. After a durable purchase claim, Mercator attempts a paid provider request at most once. A permanent failure skips dependent nodes, while independent nodes can finish. Completed purchases remain billable.

To read only the outputs you need, request a summary, then select a successful node:

curl 'https://mercator.sh/v1/jobs/{{JOB_ID}}?result_mode=summary'
curl 'https://mercator.sh/v1/jobs/{{JOB_ID}}/results/{{NODE_ID}}'
curl --get 'https://mercator.sh/v1/jobs/{{JOB_ID}}/results/{{NODE_ID}}' \
  --data-urlencode 'result_pointer=/results/0'

Recover historical jobs

Call list_jobs({ limit: 10 }) with an OAuth bearer or verified Tempo Wallet account session to find your wallet's retained jobs. Use a returned jobId with get_job to retrieve cached outputs for free. Pass nextCursor (the last job ID) as cursor to continue, keeping the same optional status filter. If that job expires, restart without a cursor. Job records, cached results, and charged idempotency records expire after seven days. History does not preserve reports composed by your agent.

Wallet sign-in grants history access without creating a spending key. Revoking an agent connection does not remove your account session's access. REST and both MCP endpoints accept either identity; an explicit invalid bearer is rejected even when a valid session cookie is present.

From a signed-in, same-origin browser, read history with the existing HttpOnly session:

const history = await fetch('/v1/jobs?limit=10', { credentials: 'same-origin' }).then(
  (response) => response.json(),
)

Cookie-authenticated requests must be same-origin. For external clients, use your OAuth access token for /mcp/auth:

curl 'https://mercator.sh/v1/jobs?limit=10&status=succeeded' \
  -H "Authorization: Bearer $MERCATOR_ACCESS_TOKEN"

Pass the returned nextCursor as the cursor query parameter for the next page. The response includes jobs, optional nextCursor, and next_action; provider payloads stay private.

Key concepts

• Plan: An immutable directed acyclic graph of 1–10 service calls. Each node declares its endpoint, input, and dependencies; Mercator derives prices from live quotes.
• Job: One durable execution of an approved plan. Mercator will execute nodes concurrently whenever possible.
• Failures: A failed job includes sanitized per-node nodeId, serviceId, and reason entries; raw provider errors remain private.
• Rank: Final display order after provider preference and health routing.
• Score: Unchanged relevance and price components. Routing can place a lower score before a higher one.

Mercator sends each provider its schema-validated input, explicitly referenced dependency output, a provider-scoped idempotency key, and the payment credential for that purchase. It does not send the full workflow or the client's wallet credentials.

Costs and payment

• Free: Discovery, service inspection, quotes, result reads, and product feedback.
• Paid jobs: The quote includes provider costs and Mercator's cost multiplier. You pay the quoted total before execution.
• Job reviews: Free; require proof from the original payer.

Quotes are advisory and do not create payment credentials or purchase provider results. Mercator validates live payment terms again during execution while enforcing the accepted total and stored per-node limits. Plans contain no client-owned prices: quote_plan returns totalAmount, and create_job passes it unchanged as approved_total. Hosted OAuth limits and any explicit budget cap spending. Legacy MCP challenge clients and separate local wallets require quote approval or a sufficient explicit budget, including after a price change.

Do not paste or send private keys. Wallet tooling handles signing and payment authorization; Mercator receives only the protocol credentials needed for the approved request.

Mercator supports MPP with two payment methods:

• Tempo: Mercator advertises a USDC.e charge. Clients can fund it with MACH through the canonical swapper, pay USDC.e directly, or use a supported pathUSD auto-swap.
• Stripe: Pay in USD with a shared payment token (SPT).

Mercator pays providers through MPP on Tempo or x402 on Base. Base is not a customer payment rail. Stripe automatic payment recovery is not supported; contact support if a payment is interrupted.

Mercator's Tempo payment clients use mercator.sh for MPP client attribution in on-chain transfer memos. Downstream payments also retain the provider's payment realm.

Failed-job refunds

Unused capacity on failed Tempo jobs is refunded to your wallet in MACH at a 1:1 value. Stripe payments are not automatically refunded.

MACH

MACH is a USD-denominated credit on Tempo for paying approved merchants, including Mercator.

• View or add MACH: Open Account. Hosted MCP users can also ask their agent to call fund_wallet.
• Claim the social grant: Run mercator account claim github or mercator account claim x, or ask an agent to call claim_wallet.
• One grant per wallet: A wallet can claim once per campaign across GitHub and X. A prior claim disables both options, including for tester accounts.
• Purchase rate: 1 USD buys 1 MACH, minted directly to the authenticated Tempo wallet.
• Automatic use: The connected wallet uses MACH for paid Mercator jobs after funding completes.

Before purchasing, confirm the wallet address. MACH:

• Can be sent only to approved merchants, including Mercator.
• Cannot be moved between personal wallets.
• Cannot be redeemed for cash, swapped, or bridged by Mercator.
• Does not expire.

The Tempo mainnet token contract is 0x20c000000000000000000000f37de3740ADec032.

Social claim browser security

Start a social claim in the same browser that completes GitHub or X authorization. The first POST /v1/claims response requires a matching Origin and sets a secure, HTTP-only cookie. Retain it and retry the identical request once. Keep that cookie for the provider callback; concurrent claims use separate cookies.

A copied authorization link cannot complete the claim in another browser. If the cookie expires or is cleared, start a new claim. Replaying an existing claim cannot change its recipient.

Service feedback

Mercator combines relevance, price, reliability, and user-reported quality when surfacing tools. After a job reaches a terminal state, an agent can review:

• The complete workflow.
• Up to 25 executed nodes.

Eligible reviews may receive 0.01 MACH after successful reward issuance. Feedback and individual tool reviews are retained for 90 days.

Feedback criteria

Reward eligibility additionally requires:

• Submission within five minutes of job completion.
• Retained customer spend after refundable unused capacity strictly greater than 0.01.

Example request

Ask an MCP-connected agent to call create_job_review. It returns a bounded command equivalent to:

mercator local submit \
  --url 'https://mercator.sh/v1/jobs/<job-id>/feedback' \
  --max-spend 0 \
  --body '{
    "rating": 5,
    "comment": "Useful result and good value.",
    "tools": [
      {
        "nodeId": "first_call",
        "rating": 5,
        "comment": "Returned the right source quickly.",
        "tags": ["accurate", "fast"]
      }
    ]
  }'

The command requires an existing local wallet that matches the original job payer. Hosted MCP authorization does not create that local wallet. The CLI obtains the zero-value challenge and uses the local wallet to sign the proof; it transfers no tokens.

If the reward is queued, poll its status:

curl 'https://mercator.sh/v1/jobs/<job-id>/feedback'

Mercator for service owners

Mercator ingests reviewed catalogs and endpoint metadata for services that use supported open payment protocols such as MPP and x402.

To request discovery, email mercator@tempo.xyz with:

• Service URL.
• Documentation or OpenAPI URL.
• Supported payment protocol.
• Short capability description.

Reporting bugs

Ran into an issue with Mercator? Report it through either channel:

• Email mercator@tempo.xyz.
• Ask an MCP-connected agent to call send_product_feedback.

For an issue involving a known job:

• Provide its UUIDv4 in the optional job_id field.
• Omit job_id when no job was created or its ID is unknown.
• Use the same field with POST /v1/product-feedback.
• Treat the ID as a result-access capability. It is shared with maintainers for investigation.

Do not include:

• Secrets, credentials, or payment material.
• Personal data.
• Raw tool inputs or outputs.

Use the job feedback endpoint for workflow and service-quality reviews, not product bugs.

Agent setup

Start with Set up Mercator for the connection and verification checklist, or choose your app below for detailed instructions.

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.

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.

mercator setup --client claude

mercator setup --client codex

mercator setup --client cursor

mercator setup --client vscode

mercator setup --client gemini

cline mcp

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

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.

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

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

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

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

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