Mercator docs

Overview

Mercator allows agents to find tools that match the needs of an open-ended workflow, quote an immutable plan of one or more tool calls, and pay for execution as one durable job.

Mercator supports any service powered by open payment protocols such as MPP and x402. Each downstream service remains independently operated, with Mercator providing search, ranking, and durable execution behind a single interface and payment flow.

AgentIntent + budget

→

Mercator

01Search the webparallel

02Enrich recordsparallel

03Compose resultafter 01 + 02

→→→

Downstream services

ExaWeb search

StableEnrichCompany data

OpenAIModel inference

Installation

Install the Mercator CLI and start interactive setup:

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

Configuration

Pass setup arguments after sh -s --:

curl -fsSL https://mercator.tempo.xyz/install.sh | sh -s -- --client codex

Desktop-only machines do not need the Codex CLI. Mercator copies its bundled plugin into Codex's user-local plugin index; no marketplace publication or management is required. Restart ChatGPT desktop after setup to load it. Use --no-plugin for CI, headless servers, or an explicitly CLI-only setup. mercator doctor reports the plugin path, version, registration state, and restart requirement. mercator uninstall removes only Mercator's CLI-managed bundle and local entry.

Manual installation

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

Manual MCP registration enables discovery and quoting. Paid execution also needs a payment runtime.

Run the automated installer or mercator wallet to set one up.

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.tempo.xyz/mcp.

REST request and response schemas and their MCP equivalents share canonical schemas. MCP tool names, descriptions, annotations, and input and output schemas are generated from the same typed contract used by the live server and OpenAPI document.

MCP tools

Key concepts

• Plan: An immutable directed acyclic graph of 1–100 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.

Costs and payment

Discovery, service inspection, quoting, result polling, and feedback are free. Paid jobs cost the freshly quoted provider total plus Mercator's advertised multiplier. Mercator accepts that exact amount before execution and preserves each node's quoted provider guard.

Mercator accepts payment on Tempo mainnet through either method:

• Reusable MPP session: Authorize USDC.e once. Each accepted job advances the session by the exact freshly quoted amount.
• One-time direct charge: Pay the exact freshly quoted amount in MACH, with USDC.e as a fallback.

MACH

MACH is a closed-loop, USD-denominated token on Tempo. Think of it as merchant credit rather than a general-purpose stablecoin.

Run mercator wallet fund to buy MACH. $1 buys 1 MACH, which is minted directly to the Tempo wallet selected at checkout. Confirm the address before buying: the balance cannot be moved to another personal wallet afterward.

MACH can be sent only to approved merchants, including Mercator. Transfers between ordinary wallets are rejected, and Mercator does not offer cash redemption, swaps, or bridges. MACH balances do not expire.

Once funded, the wallet automatically uses MACH for Mercator payments. Discovery and quoting remain free.

Service feedback

Mercator aims to surface the best tools for a query by combining relevance, price, reliability, and user-reported quality. After a job reaches a terminal state, an agent can leave a review of the workflow and up to 25 individual executed nodes.

Agents that provide high-quality reviews for eligible jobs may receive 0.01 USD in pathUSD.

Feedback criteria

Reward eligibility additionally requires:

• Submission within five minutes of job completion.
• Purchased-provider spend greater than 0.01.

Example request

curl -X POST 'https://mercator.tempo.xyz/v1/jobs/<job-id>/feedback' \
  -H 'Content-Type: application/json' \
  --data '{
    "rating": 5,
    "comment": "Useful result and good value.",
    "tools": [
      {
        "nodeId": "first_call",
        "rating": 5,
        "comment": "Returned the right source quickly.",
        "tags": ["accurate", "fast"]
      }
    ]
  }'

If the reward is queued, poll its status:

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

Mercator for service owners

Mercator can discover and execute services that use supported open payment protocols such as MPP and x402.

Interested in getting your service discovered? Email mercator@tempo.xyz with:

• service URL
• documentation or OpenAPI URL
• supported payment protocol
• a short description of its capabilities.

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 after you explicitly approve the report.

Bug reports must not include secrets, credentials, payment material, personal data, job IDs, or raw tool inputs and outputs. The job feedback REST endpoint is for workflow and service-quality reviews, not product bug reports.

FAQ