Discovery Spec

Build once, register reliably, and keep your MPP resources discoverable.

Why This Matters

If agents can't discover your API, they can't call it. Bulletproof discovery turns your endpoint from merely listed to reliably invocable.

When metadata and runtime 402 behavior agree, agents succeed on the first pass. You get fewer MPPScan failures, less debugging churn, and more real agent traffic.

Publish OpenAPI as the canonical machine-readable contract.
Treat runtime 402 challenge behavior as the final source of truth.

Copy for Agents

Paste this directly into your coding agent. It should handle discovery implementation and validation end-to-end.

Implement AgentCash discovery for this server and make it pass.

Discovery strategy:
Your api should expose an OpenAPI document at /openapi.json, which abides by the OpenAPI specification,
with several additional fields required for MppScan and AgentCash discovery.
You can use the @agentcash/discovery package to validate your OpenAPI document.

Validation commands:
npx -y @agentcash/discovery@latest discover "$TARGET_URL"
npx -y @agentcash/discovery@latest check "$TARGET_URL"


This will yield warnings regarding the discovery document and how it can be improved.

Schema guidance (important):
- Each invocable route should expose an input schema.
- In OpenAPI, define requestBody.content["application/json"].schema.
- This is required for reliable agent invocation and robust listing behavior.
- Add high-level guidance in info.guidance for agent-friendly discovery. This document should explain to an agent how to use your API at a high level.

OpenAPI payable operation must include ALL:
- x-payment-info with:
  - protocols: ["mpp"]
  - pricingMode + fields:
    - fixed: { pricingMode: "fixed", price: "<amount>" }
    - range: { pricingMode: "range", minPrice: "<min>", maxPrice: "<max>" }
    - quote: { pricingMode: "quote" }
  - IMPORTANT: for fixed pricing use "price" (not "amount")
- responses: { "402": { description: "Payment Required" } }

Minimal valid example:
{
  "openapi": "3.1.0",
  "info": {
    "title": "My API",
    "version": "1.0.0",
    "description": "example demo server",
    "guidance": "Use POST /api/search for neural web search. Accepts a JSON body with a 'query' field."
  },
  "x-discovery": {
    "ownershipProofs": ["<proof-1>"]
  },
  "paths": {
    "/api/search": {
      "post": {
        "operationId": "search",
        "summary": "Search - Neural search across the web",
        "tags": ["Search"],
        "x-payment-info": {
          "pricingMode": "fixed",
          "price": "0.010000",
          "protocols": ["x402", "mpp"]
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "query": { "type": "string", "minLength": 1, "description": "The query string for the search" }
                },
                "required": ["query"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "results": { "type": "array", "items": { "type": "object" } }
                  },
                  "required": ["results"]
                }
              }
            }
          },
          "402": { "description": "Payment Required" }
        }
      }
    }
  }
}


Workflow:
1) Validate your OpenAPI document with the @agentcash/discovery package.
2) Fix your OpenAPI document until it passes validation.
3) Register your server on MPPScan once it passes validation.

Discovery Strategy

OpenAPI is the canonical discovery format. Use it for the cleanest machine-readable contract and best agent compatibility.

OpenAPI Implementation

Use this first. It gives the cleanest machine-readable contract and best tooling compatibility.

Expected location: GET /openapi.json

Top-level fields: openapi, info.title, info.guidance, info.version, paths.
For paid operations: responses.402 and x-payment-info.
Set x-payment-info.protocols and one pricing mode (fixed, range, quote).
Use OpenAPI security + components.securitySchemes for auth declaration.
Add high-level guidance in info.guidance for user-friendly discovery.

{
  "openapi": "3.1.0",
  "info": {
    "title": "My API",
    "version": "1.0.0",
    "description": "example demo server",
    "guidance": "Use POST /api/search for neural web search. Accepts a JSON body with a 'query' field."
  },
  "x-discovery": {
    "ownershipProofs": ["<proof-1>"]
  },
  "paths": {
    "/api/search": {
      "post": {
        "operationId": "search",
        "summary": "Search - Neural search across the web",
        "tags": ["Search"],
        "x-payment-info": {
          "pricingMode": "fixed",
          "price": "0.010000",
          "protocols": ["x402", "mpp"]
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "query": { "type": "string", "minLength": 1, "description": "The query string for the search" }
                },
                "required": ["query"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "results": { "type": "array", "items": { "type": "object" } }
                  },
                  "required": ["results"]
                }
              }
            }
          },
          "402": { "description": "Payment Required" }
        }
      }
    }
  }
}

Discovery Precedence

MPPScan uses the OpenAPI document at /openapi.json to discover your API. It will also check the runtime 402 challenge behavior to ensure it is correct.

Order	Source	Expected Location
1	OpenAPI document	`/openapi.json`
2	402 API Response	`WWW-Authenticate header`

Common Failure Reasons

These are the most frequent errors seen during registration.

Error	Likely Cause	Fix
`Not Found`	OpenAPI not found at {origin}/openapi.json	Add a OpenAPI document at {origin}/openapi.json
`Input/Output Schema Missing`	Operation has no input or output schema	Add an input and output schema to the operation
`WWW-Authenticate Header Missing`	Invalid WWW-Authenticate header	Add a valid MPP-based WWW-Authenticate header
`Payment/Auth Mode Missing`	x-payment-info.protocols is missing	Add x-payment-info.protocols.pricingMode