Read the map before you browse.

Free public MCP beta

Connect your agent to Webterra

Search the public catalog anonymously, connect a free developer account with OAuth, or keep using your existing API key. All three methods expose the same read-only public evidence.

Try without an account

Add this Streamable HTTP server in a client that accepts remote MCP configuration. Omit authorization entirely for anonymous access.

Production endpoint: https://project-uiuj9.vercel.app/mcp/v2

{
  "mcpServers": {
    "webterra": {
      "url": "https://project-uiuj9.vercel.app/mcp/v2"
    }
  }
}

For Codex CLI, run codex mcp add webterra --url https://project-uiuj9.vercel.app/mcp/v2. For Cursor, merge the JSON into your project’s .cursor/mcp.json. Preserve existing server entries. Other hosts may use different configuration formats.

Connect a developer account with OAuth

1. Create a free Webterra account and confirm its verification email, or sign in to your existing account.
2. Open Manage OAuth connections, choose Connect with Auth0, and create or sign in to your catalog identity. Complete any email verification and approve catalog-read consent. Use this same Auth0 identity in your MCP client.
3. Add one of the client configurations below. Client IDs are public identifiers; no client secret is needed. Sign in through the browser when your client requests it.

This explicitly links the two signed-in accounts. Matching email addresses alone never link accounts. OAuth and API keys share your existing 10,000 monthly catalog reads; OAuth grants no owner or operator privileges.

Codex CLI

Merge this entry into ~/.codex/config.toml without replacing other servers, then run codex mcp login webterra_oauth. Restart the client after changing its configuration.

[mcp_servers.webterra_oauth]
url = "https://project-uiuj9.vercel.app/mcp/v2/auth"
scopes = ["map:read", "offline_access"]

[mcp_servers.webterra_oauth.oauth]
client_id = "tpc_7jKT3SMyAhCj1eBFCiWVYs"
callback_url = "http://127.0.0.1:44321/callback"
callback_port = 44321

Cursor desktop and CLI

Merge this entry into .cursor/mcp.json and use its Connect or login action. The approved callback is http://localhost:8787/callback; this setup does not authorize Cursor’s cloud callback. In Cursor CLI, use agent mcp login webterra-oauth.

{
  "mcpServers": {
    "webterra-oauth": {
      "url": "https://project-uiuj9.vercel.app/mcp/v2/auth",
      "auth": {
        "CLIENT_ID": "tpc_9SygyHe28HiiXXbyGr9jHx",
        "scopes": [
          "map:read",
          "offline_access"
        ]
      }
    }
  }
}

These clients use pre-registered public IDs and PKCE. Dynamic client registration is not enabled. The protected /mcp/v2/authpath deliberately starts OAuth even when anonymous access is available. A tool listing confirms discovery; invoke search_sites or get_task_evidence to verify a useful read.

Disconnect in Manage OAuth connections to stop access on the next request, and remove the saved connection in your client. Reconnecting restores the same account and remaining allowance. Clients can refresh tokens within the provider’s expiry window; sign in again when required.

Keep using an API key

After email verification, open Developer API keys in your dashboard, issue a key and copy it once. Store it in your client’s secure credential configuration, and revoke it in the dashboard when finished. Existing self-service developer keys keep their 10,000/month allowance.

{
  "mcpServers": {
    "webterra": {
      "url": "https://project-uiuj9.vercel.app/mcp/v2",
      "headers": {
        "Authorization": "Bearer YOUR_WEBTERRA_KEY"
      }
    }
  }
}

Replace YOUR_WEBTERRA_KEY locally; never commit a key or paste it into chat. An invalid, expired or revoked credential is rejected. Do not remove a rejected credential to retry anonymously.

Eleven read-only catalog tools

Start with search_tasks or search_sites, then inspect the returned identity, interfaces and evidence. Use find_best_route for a condition-matched recommendation. Mapped records may have no tested routes; an empty or insufficient-evidence response is a valid answer.

Compatibility & access

Choose an explicit contract

Responses carry schema, data and policy versions. A no_verified_route, unavailable, stale, or empty result is an outcome to preserve—not a reason to guess a route.

Integration path

Four safe steps

1. 01

   Choose a task or site

   Start with a stable published ID or normalized search query. Do not send credentials or personal intent details.

2. 02

   Query conditions

   Filter by objective, interface, region, authentication context, and agent configuration where supported.

3. 03

   Interpret evidence

   Carry the data version, freshness, denominator, provenance, and limitation with every result.

4. 04

   Fall back safely

   Treat unknown, stale, blocked, and no-match responses as honest outcomes—not permission to assume success.

Keys, quotas & errors

Keys add capacity, not authority

Sign in to the Control dashboard to issue one active developer key, copy it once, and revoke it when it is no longer needed. Keys are scoped to catalog reads and the separate consented feedback exchange; they cannot list another tenant’s reports, browse a site, or dispatch work.

Anonymous access allows up to 100 useful reads per normalized IP bucket per UTC day. Shared across Web and MCP, the global ceilings are 1,000 useful anonymous reads/day, 2,000 anonymous transport attempts/day and 60 anonymous attempts/minute. Shared networks share the per-IP allowance. Account access retains 10,000 reads per UTC calendar month across keys and OAuth, with a 120-request-per-minute account limit. The shared service ceiling is 120 attempts/minute and two active catalog reads. These are maximum limits, not throughput or availability guarantees.

Initialize and tool discovery consume transport attempts, not useful reads. A successful catalog invocation counts once, including empty results. Handle 401 by repairing or renewing credentials,403 by checking account linking and read permission,429 by respecting Retry-After, and503 as temporary unavailability. Quota errors do not authorize credential switching or automatic retries.

The optional TypeScript feedback helper is a thin client for the REST read and explicit Control receipt/report endpoints. It is not a source of truth and does not execute a recommended route. Customer-reported observations remain quarantined from public reliability and ranking.