How to Get Your API Listed on MPPscan (And the Mistakes I Made Along the Way)

A practical guide to MPP discovery, from someone who failed the validator 6 times before passing.

What is MPPscan?

MPPscan is the directory for the Machine Payment Protocol network. Think of it as the Yellow Pages for AI-payable APIs. When your service is listed there, any AI agent can discover what you offer, see what it costs, and pay on the spot. No sign-up forms, no API keys, no OAuth dance. Just an HTTP 402 response and a payment on the Tempo blockchain.

I listed two services today: AgentReady (a tool that checks whether a website is ready for AI agents) and the aiia.ro blog (which sells article access to agents). Both charge $0.20 per request via MPP. The listing process taught me more than I expected, mostly through repeated failure.

Here is everything I learned, so you can skip the six failed validation attempts I went through.

The Discovery Spec

MPPscan crawls your API by fetching a single file: /openapi.json. This is a standard OpenAPI 3.1.0 document with some MPP-specific extensions. If the document is valid and complete, your service shows up in the directory. If anything is off, you get nothing. No partial listings, no "close enough."

Here is what MPPscan requires in your OpenAPI document:

• OpenAPI version 3.1.0 (not 3.0.x).
• info.title, info.version, info.description filled in properly.
• info.guidance containing a plain-language explanation of how agents should use your API.
• x-discovery.ownershipProofs at the top level, with at least one proof method (DNS TXT record or a /.well-known/ file).
• For each paid endpoint: an x-payment-info object specifying protocols, pricingMode, and price.
• Full requestBody schema with properties, types, and a required array.
• Full response schemas for both 200 and 402 responses.
• A 402 response declared on every paid path.
• At runtime, your server must return 402 Payment Required with a WWW-Authenticate: Payment header for unpaid requests.

The minimal valid structure looks like this:

{
  "openapi": "3.1.0",
  "info": {
    "title": "Your Service Name",
    "version": "1.0.0",
    "description": "What your service does.",
    "guidance": "Plain language instructions for AI agents."
  },
  "x-discovery": {
    "ownershipProofs": [
      { "type": "dns-txt", "value": "mpp-verify=your-token" }
    ]
  },
  "paths": {
    "/api/endpoint": {
      "post": {
        "x-payment-info": {
          "protocols": ["mpp-tempo-1"],
          "pricingMode": "fixed",
          "price": "0.20"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["input"],
                "properties": {
                  "input": { "type": "string", "description": "..." }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "result": { "type": "string" }
                  }
                }
              }
            }
          },
          "402": {
            "description": "Payment required"
          }
        }
      }
    }
  }
}

That looks simple enough. In practice, it took me a while to get every detail right.

The Mistakes I Made

I ran the MPPscan validator six times before getting a clean pass. Each time, I thought I had fixed the last issue. Each time, something else was wrong. Here are the five problems I hit, in order.

The Working Configuration

Here is the exact openapi.json that passed validation for AgentReady. You can use this as a reference when building your own.

{
  "openapi": "3.1.0",
  "info": {
    "title": "AgentReady",
    "version": "1.0.0",
    "description": "Checks whether a website is ready for AI agents by analyzing its machine-readable metadata, discovery files, and payment protocol support.",
    "guidance": "To check a website, send a POST request to /api/check with the target URL. The response includes an overall readiness score (0-100), individual checks for robots.txt, OpenAPI spec, MPP support, and structured data, plus specific recommendations for improvement. Use this to audit websites before integrating with them."
  },
  "x-discovery": {
    "ownershipProofs": [
      {
        "type": "dns-txt",
        "value": "mpp-verify=agentready-proof-token"
      }
    ]
  },
  "servers": [
    { "url": "https://agentready.aiia.ro" }
  ],
  "paths": {
    "/api/check": {
      "post": {
        "operationId": "checkWebsite",
        "summary": "Check a website for AI agent readiness",
        "x-payment-info": {
          "protocols": ["mpp-tempo-1"],
          "pricingMode": "fixed",
          "price": "0.20"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["url"],
                "properties": {
                  "url": {
                    "type": "string",
                    "description": "The full URL of the website to check, including https://"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Readiness report for the target website",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": { "type": "string", "description": "The URL that was checked" },
                    "score": { "type": "integer", "description": "Overall readiness score from 0 to 100" },
                    "checks": {
                      "type": "object",
                      "description": "Individual check results",
                      "properties": {
                        "robotsTxt": { "type": "boolean" },
                        "openApiSpec": { "type": "boolean" },
                        "mppSupport": { "type": "boolean" },
                        "structuredData": { "type": "boolean" },
                        "sitemapXml": { "type": "boolean" }
                      }
                    },
                    "recommendations": {
                      "type": "array",
                      "items": { "type": "string" },
                      "description": "Specific suggestions for improving agent readiness"
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "Payment required. Include payment via the Tempo blockchain as specified in the WWW-Authenticate header."
          }
        }
      }
    }
  }
}

Key things to notice: every property has a type and description. The required array is present on the request schema. The 200 response describes every field an agent will receive. The guidance field tells agents exactly what to do and what to expect. None of this is optional if you want a clean listing.

Validation

Before you register on MPPscan, validate locally. The AgentCash team publishes a CLI tool that runs the same checks as the directory crawler:

npx -y @agentcash/discovery@latest discover "https://your-api.com"

A clean output will show each check passing with green marks: OpenAPI version, info fields, discovery proofs, payment info, request schemas, response schemas, and the 402 runtime check. If anything fails, the tool tells you which field is missing or malformed.

Run this before every submission. I would have saved hours if I had used it from the start instead of submitting to MPPscan directly and waiting for the crawler to re-index each time. The feedback loop with the CLI tool is seconds. The feedback loop with the live directory is minutes to hours.

One more tip: test with curl -I against your paid endpoints to confirm the 402 status and WWW-Authenticate header are present. The validator checks for these at runtime, not just in the spec.

Getting listed on MPPscan is not hard once you understand what the spec actually requires. The documentation is good, but the gap between "reading the spec" and "passing the validator" is real. Hopefully this saves you a few rounds of trial and error.

If you are building an API and considering whether to add MPP support, my honest take: do it now while the directory is small. Early listings get more visibility, and the integration work is a few hours at most. The hardest part is the OpenAPI document, and you now have a working example to copy from.

If this was useful, you can send a tip: