Surface Contract: how platform APIs really behave

Measured conclusion: Deep-tested. L2 outcome: tools_ok.

Evidence-cited machine-readable contracts for how agent platform APIs really behave

Measured statistics

Add to your agent

Copy this into your MCP client config:

{
  "mcpServers": {
    "Surface Contract: how platform APIs really behave": {
      "url": "https://penny-surface-contract.penny-mcamp.workers.dev/mcp",
      "transport": "streamable-http"
    }
  }
}

Measured tools (7)

• list_surface_contracts

  List the platform surface contracts published in Penny's free registry, with claim counts.

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• get_surface_contract

  Get the machine-readable surface contract for a platform host (read/write semantics, pending states, rate limits, limits, idempotency, pagination completeness, data portability), each claim carrying its evidence and its verification status.

  Parameters:

  • id (required) — string — contract id or host, e.g. moltbook or www.moltbook.com

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• verify_surface

  Run the anonymous conformance checks for a contract now and return verified / failed / unknown / manual / unsupported per claim.

  Parameters:

  • id (required) — string

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• contribute_discrepancy

  Report a platform behaviour that contradicts a published claim, or a new claim, with evidence. One-line call: POST /v1/contribute with {contractId, kind, statement, evidence[], reporter, observedAt}. Stored as pending; a published contract is never changed without independent verification. A contractId no published contract serves is accepted as a NEW-PLATFORM PROPOSAL: the 202 body carries contractExists:false (with proposal:true, proposedContractId and proposedHost), it is listed distinctly at GET /v1/contributions, and it stays pending until a second party reproduces it - it never creates or mutates a contract. A proposal filed by us reads selfProbe:true in that listing, and GET /v1/contributions counts proposals filed by non-self submitters separately from our own self-probes, so only the non-self number is outside coverage.

  Parameters:

  • contractId (required) — string — the platform's contract id or host; an id no published contract serves is accepted as a new-platform proposal (contractExists:false)
  • kind (required) — string
  • statement (required) — string
  • evidence (required) — array
  • claimId — string
  • reporter — string — your agent or operator name, so the record is attributed to you and is not read as one of ours (an unattributed record is counted non-self AND flagged noReporter)
  • observedAt — string — ISO 8601 date you observed the behaviour; a claim without a date is not a measurement

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• get_integration_recipe

  Get a plain-text integration recipe for a platform: the order of operations to use it, and a guard clause for every behaviour we measured going wrong, each naming the contract claim behind it. Derived from the contract, so it cannot drift from it.

  Parameters:

  • id (required) — string — contract id or host, e.g. moltbook

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• preflight_mcp_server

  Run the anonymous MCP handshake against ANY https MCP endpoint you name, right now, and get back a verdict (open / refused / unreachable / initialize-transport-error), the shape of any refusal body, whether the server is stateful (sets Mcp-Session-Id), how many tools tools/list returns, and the guard clauses that follow. Use it before wiring an MCP server into your own config. Pass `urls` (up to 5) to check a whole mcp.json in one call. When the endpoint refuses, it also reports whether the refusal advertises a credential path (an RFC 9728 resource_metadata pointer) and whether that pointer resolves to a metadata document naming an authorization server, so you learn where a token would come from without writing that parsing yourself. No credential is sent, none is obtained, and none of their tools is ever called.

  Parameters:

  • url — string — absolute https URL of the MCP endpoint, e.g. https://host/mcp
  • urls — array — batch form: 2 to 5 absolute https URLs, checked with the same battery in one call (each one counts against the same daily egress budget as a single preflight)

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• prepay_check

  Check an x402 route BEFORE you pay it. GET /v1/prepay?url=<the route> makes ONE unpaid GET with no payment header and no credential, and returns one row: the measured HTTP status, the parsed x402 v2 challenge (scheme / network / asset / amount / payTo), whether that challenge is schema-valid exact-on-Base, and whether its payTo and price agree with the seller's own card (pass `card` to read that card with one more unpaid GET). No payment is made, no credential is sent, no redirect is followed, and a transport failure on our side is reported as unknown rather than as a fact about the seller. Use it to gate a payment decision on measured terms instead of on a seller's prose.

  Parameters:

  • url (required) — string — absolute https URL of the route you are about to pay
  • card — string — optional: absolute https URL of the seller's own card/listing page, read with one more unpaid GET to compare the wallet and the price it advertises (agreement is true|false|unknown, and unknown is null, never false)

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

Publisher website

Measured by MCPYP probing. Untested fields are omitted, never estimated. Listing is always free; MCPYP never proxies calls or stores user tokens.