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 for a location before spending. The free locus_lane_availability tool is the know-before-you-pay preflight: give it a ZIP or address and it returns which lanes work there — national, local, varies, or not covered — plus, per paid tool, a price, manifest URL, and a buy signal. Works for any geocodable US address.
  • 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

{
  "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: which lanes return data for a ZIP/address (national / local / varies / not covered), with a per-paid-tool price, manifest, and buy signal. Know before you pay.
  • 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. The compiled paid tools — the place report (locus-place-report), the local trend brief, the local policy brief, before-you-sign, and the environmental-context brief — are gated with x402 micropayments in USDC on Base. Prices and the recipient are authoritative in the live paid-tool manifest — read them from there, never hardcode them.

The flow is the standard x402 challenge-and-repeat, and it is the same whether you call over REST, MCP, or A2A:

  1. Call the paid tool without payment. REST: POST https://api.locus.report/api/<tool-slug> (the place report also answers at POST /api/analyze). MCP: locus_execute. A2A: POST /a2a/v1/message:send.

  2. Read the 402 challenge. A covered place returns HTTP 402 with a JSON body whose accepts[] carries the payment requirements:

    {
      "x402Version": 2,
      "accepts": [
        {
          "scheme": "exact",
          "network": "eip155:8453",
          "maxAmountRequired": "<amount in USDC base units>",
          "payTo": "0x… (Locus recipient)",
          "asset": "0x… (Base USDC)",
          "resource": "https://api.locus.report/api/locus-place-report",
          "extra": { "assetTransferMethod": "eip3009", "name": "USD Coin", "version": "2" }
        }
      ]
    }

    Use the values from the live challenge — not these placeholders — to build the payment.

  3. Pay and repeat. Sign an EIP-3009 USDC transfer authorization for maxAmountRequired to payTo on network (an x402 client such as x402-fetch / x402-axios, or the Coinbase x402 SDK, does this), put it in the X-PAYMENT request header, and resend the identical request.

  4. Receive the artifact. On settlement Locus returns the paid result plus an X-PAYMENT-RESPONSE header with the settlement reference.

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.

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.