Skip to content
Locus Locus Docs

Agent workflows

This is the public integration overview. For machine-readable instructions, point the agent at:

https://docs.locus.report/skill.md

For Codex-style agents, install the Locus skill directly:

Terminal window
npx @velinussage/locus-agent-skill add

What an agent can do

  • Check what works before spending. Summary lane availability is short; request detailLevel: "full" or read the paid index for exact paid-only atomic buy signals.
  • Pull property context such as taxes, flood, zoning, environmental records, permits, development cases, policy artifacts, and transportation projects.
  • Ask for a focused report or brief instead of a broad crawl.
  • Keep a property picture current through recurring monitoring.
  • Return verification questions instead of unsupported conclusions.

MCP

Add Locus to Claude Code with one command:

Terminal window
claude mcp add --transport http --scope user locus https://mcp.locus.report/mcp

For other MCP clients, use this configuration:

{
  "mcpServers": {
    "locus": {
      "type": "http",
      "url": "https://mcp.locus.report/mcp"
    }
  }
}

Transport is streamable HTTP at https://mcp.locus.report/mcp — point any MCP client at that URL. Discovery and the free coverage tools need no auth. Running a paid tool requires an x402 payment in the same locus_execute call (see Paying for paid tools below).

The MCP server exposes:

  • locus_search_tools — search the live catalog.
  • locus_execute — run one selected tool by name (free tools run immediately; paid tools return an x402 challenge until payment is attached).

The free coverage/availability tools an agent should call first:

  • locus_lane_availability — the per-address preflight. Use detailLevel: "full" for a specific paid-only atomic.
  • locus_coverage_check — a single place’s trend / parcel / policy coverage.
  • locus_coverage_map — the whole registry: every lane and where it is covered.

A2A and REST

Live catalogs are the source of truth for tool names, schemas, and prices.

Paying for paid tools (x402)

Discovery, coverage, and the free /tools/call façade never charge. Paid tools use x402. The seven paid-only atomic research routes are REST-only; MCP and A2A expose only their own catalog entries.

The payment requirements are the same on each rail, but the challenge and receipt containers differ:

  1. Call on a supported rail. REST: POST /api/<tool-slug>. MCP: locus_execute for MCP-listed tools. A2A: message send for A2A-listed tools.

  2. Read the challenge. REST returns HTTP 402. A2A returns HTTP 200 with an input-required task and payment metadata. MCP returns a tool error result with payment metadata.

    {
      "x402Version": 2,
      "accepts": [
        {
          "scheme": "exact",
          "network": "eip155:8453",
          "amount": "<amount in USDC base units>",
          "payTo": "0x… (Locus recipient)",
          "asset": "0x… (Base USDC)",
          "extra": { "assetTransferMethod": "eip3009", "name": "USD Coin", "version": "2" }
        },
        {
          "scheme": "exact",
          "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
          "amount": "<same price in USDC base units>",
          "payTo": "<Locus Solana recipient>",
          "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
          "extra": { "feePayer": "<facilitator fee payer from the live challenge>" }
        }
      ]
    }

    Choose one complete entry and use its live values. Never combine fields across Base and Solana offers.

  3. Pay and repeat. REST uses PAYMENT-SIGNATURE. MCP uses _meta["x402/payment"]. A2A reuses the task/context ids and sends x402.payment.payload in message metadata.

  4. Receive the receipt. REST uses PAYMENT-RESPONSE; MCP uses _meta["x402/payment-response"]; A2A uses x402.payment.receipts.

Always surface the price, network, and recipient to the user before paying, and only retry after authorization. Coverage comes before charge: unsupported or discovery-only places return a free diagnostic, never a 402. Payment binds to the tool and a canonical hash of the arguments (not the raw address), so a replayed or redelivered payment for the same call is idempotent and never double-charges.

Request shape

place + user goal
-> discover the smallest useful tool
-> check coverage/source fit (locus_lane_availability)
-> execute one selected tool
-> answer only from returned artifacts
-> show limits and verify-next steps

Coverage comes before payment. Unsupported or partially covered paid requests return diagnostics instead of silent charges.

Prepare satellite imagery from an address

The REST-only locus-large-site-satellite-change endpoint requires bbox in [west, south, east, north] WGS84 longitude/latitude order, plus beforeDate and afterDate (YYYY-MM-DD; after strictly later). It does not accept an address. The box must cover 1-100 km², each side at least 500 m, with aspect ratio at most 8:1.

Start with free locus_satellite_area_prepare over MCP or POST /tools/call:

{"name":"locus_satellite_area_prepare","arguments":{"address":"1 E Edenton St, Raleigh, NC 27601","beforeDate":"2024-06-01","afterDate":"2026-06-01","halfExtentMeters":1000}}

On status: "ready", review the matched subject, source, dimensions and retryInput. A 1 km expansion in each direction makes about 4 km² of surrounding-area context, not a parcel boundary. The helper rejects ambiguous or imprecise locations and never renders imagery or pays. Confirm the paid endpoint is in the live catalog, then send retryInput as the flat REST body and authorize payment separately.

{"bbox":[-78.68,35.75,-78.60,35.81],"beforeDate":"2024-06-01","afterDate":"2026-06-01","areaLabel":"Raleigh NC site"}

That direct example covers roughly 48 km², not one house. Meaningful invalid input returns 400 with charged:false and field-level issues before payment or rendering. The result is dated imagery, not automated change detection or a building-condition finding.

Data-center awareness

For a data center, compute campus, server farm, or crypto-mining concern, call locus_data_center_watch. It returns a bounded official-source search plan plus water, grid, land-use, hearing, incentive, ordinance, and local-decision paths to verify. It does not run web search or claim a match/no-match by itself; a search-capable agent must execute the query pack and cite official sources before reporting any finding.

Boundary

Locus is a property-context tool, not a decision engine. If a user asks for a score, ranking, screening decision, valuation, or safe/unsafe label, return the relevant records and verification questions instead. See Accuracy and boundaries.