# MeetMyAgent: An AI-Native Marketplace Architecture

Version 1.0 · 2026-07-10 · human version: https://meetmyagent.io/en/whitepaper

## Abstract

MeetMyAgent is a free, AI-native marketplace and business directory: people and companies list services, products, real estate, local offers, company profiles and MCP servers; humans browse a normal website while AI assistants operate the very same platform through a first-class API and an MCP server. Money only moves on deals, held by a regulated payment provider and released by explicit human approval.

This paper describes how the platform is engineered so that an autonomous agent can use it *safely*: how the catalog describes itself so agents never guess, how the API documents itself in a way that cannot silently drift from reality, how the money path is designed to make double-spending and orphaned funds structurally hard, how untrusted content is quarantined before it becomes a listing, and how feeds stay in sync without ever being able to mass-damage a portfolio. It is written for engineers, for teams evaluating the platform, and for the AI agents that will read it.

We publish it because trust in an agent-operated marketplace cannot come from marketing claims. It has to come from verifiable design — and every load-bearing claim in this document can be checked against live, public endpoints listed at the end.

## 1. The problem: marketplaces were built for human eyes

Classic marketplaces assume a human is looking at them. Their filters are drawn as sidebars, their rules live in help-center prose, their errors are rendered as red banners. An AI assistant operating such a site has to scrape, guess and hope: guess which filters exist, guess what values they accept, guess what an error meant, guess whether a button click had side effects.

That guessing is exactly what makes people distrust agents with real-world tasks — and with money. Two failure modes dominate:

- **Hallucinated structure.** The agent invents a filter, a category, or a parameter that does not exist, and either fails loudly or — worse — silently returns wrong results.
- **Unbounded side effects.** The agent performs an action a human would have wanted to review first: publishing, spending, deleting.

Horizontal marketplaces additionally die of two classic causes: **discovery** (everything is listed, nothing is findable) and **cold start** (nobody lists because nobody is there). Our thesis: an AI-operated catalog solves discovery *if and only if* the machine can query it precisely — and a free listing model plus automated supply channels solve cold start without lowering quality gates.

MeetMyAgent is designed from those constraints backwards.

## 2. Design principles

Five principles govern every feature; the rest of this paper is their consequences.

1. **The API is the platform.** Everything the website does goes through the same public API a third-party agent would use. The web UI is a thin client; there is no privileged back channel. If a capability is not in the API, it does not exist.
2. **Describe, then act — never guess.** Anything an agent needs to know at runtime (categories, filterable facets, allowed values, error semantics, endpoint contracts) is published machine-readably and consumed *before* acting. Guessing is treated as a bug in the platform, not in the agent.
3. **Humans stay in the loop where it hurts.** Nothing publishes itself, nothing spends money, and nothing is taken down without an explicit human decision. Agents prepare; humans approve.
4. **Configuration is data, not code.** Categories, facets, compliance rules and settings live in the database and are served through the API. Growing the taxonomy or tightening a rule is a data change with an audit trail, not a deployment.
5. **Honesty over theater.** Where the industry overpromises — "guaranteed AI citations", "fully autonomous commerce" — we state what we can and cannot deliver. Trust compounds; hype defaults.

## 3. The self-describing catalog

### 3.1 Everything is a listing

One universal listing model carries every vertical: a core (title, description, optional price and location, media, provider, status, embedding) plus per-category **attributes** validated against a typed facet schema. New verticals — the *MCP servers* category is a recent example — are added as data: a category row plus facet definitions. No schema migration, no new endpoints, no code path per vertical.

### 3.2 Taxonomy as data, schema as API

Each category publishes its facets: key, label, type (enum, number, boolean, text, semantic tag, geo), allowed values for enums, numeric ranges, whether the facet is filterable or sortable, and a relevance weight. The whole registry is served at a public, unauthenticated endpoint.

The consequence is the platform's core interaction pattern, which we state as a rule for agents in every surface we publish:

> **Describe, then search.** Read the catalog schema first; construct queries only from facets and values the schema declares.

An agent that follows this pattern *cannot* hallucinate a filter — the failure mode is designed out rather than mitigated. Enum values are closed sets; numeric facets carry ranges; free text stays free text. The same schema drives the website's filter sidebar, so human and machine views can never diverge.

### 3.3 Typed queries, hybrid retrieval

Search accepts an optional natural-language query plus a list of typed facet filters, geo constraints, sort and cursor pagination. Under the hood retrieval is hybrid, in a strict order:

1. **Structured pre-filtering first.** Category, facet and geo predicates narrow the candidate set with ordinary indexed queries. Authorization and status predicates are part of this stage — a filter can never leak drafts or foreign private state, because visibility is enforced before ranking, not after.
2. **Semantic ranking second.** Within the filtered set, vector similarity between the query embedding and listing embeddings orders results. Semantics never widen the candidate set; they only order what the structured stage already admitted.

This ordering matters: it makes relevance a *ranking* concern and correctness a *filtering* concern, and it keeps the two from contaminating each other.

### 3.4 Growing filters with content

Facets are designed to grow with supply. New categories can be proposed by the intake pipeline itself when content does not fit — but proposals enter a human approval queue and never activate themselves. Approved categories persist as data and survive restarts and deployments identically to seeded ones. The schema endpoint always reflects the live state, so agents pick up new verticals without any client update.

## 4. An API that cannot quietly lie about itself

Agent trust dies the day the documentation drifts from reality. We treat the API's self-description as a *product invariant*, enforced in three layers.

### 4.1 One registry, three artifacts

Every endpoint is declared once in an internal registry: method, path, summary, authentication requirement, required scope, idempotency support. From that single source we serve:

- a **machine-readable index** at `GET /v1` — every endpoint with its auth and scope requirements plus the platform's conventions (envelope shape, pagination, idempotency headers, rate-limit headers);
- an **OpenAPI 3.1 document** at `GET /v1/openapi.json` — including the response envelope, the full closed set of stable error slugs, and per-operation security;
- the human developer pages.

### 4.2 Documentation under test

Three automated gates run against every build:

1. **Surface diff, both directions.** The registry is compared against the actual mounted route table. An endpoint that exists but is undocumented fails the build; a documented endpoint that does not exist fails the build.
2. **Contract probes.** Tests *call every endpoint* and assert its declared authentication behaves as declared: endpoints marked public must answer without credentials; endpoints marked authenticated must refuse anonymous calls with the documented error; every declared scope is probed with a wrongly-scoped token and must refuse with the scope's name in the error detail. A claim like "this endpoint needs scope X" is not prose — it is an executed assertion.
3. **Idempotency mirror.** Endpoints declaring idempotency support are cross-checked against the actual presence of the idempotency middleware in the route source.

We adopted this discipline after our own review process caught the registry claiming wrong scopes for three endpoints while a naive surface diff stayed green. The lesson generalizes: *docs that are not executed will eventually lie.* Ours are executed.

### 4.3 Predictable failure

Every response — success or failure, including unknown paths — uses one envelope with a request id. Errors carry a stable machine-readable slug from a closed, documented set, a human message, and a documentation URL. Write endpoints accept an idempotency key; retries with the same key return the original outcome instead of repeating side effects. Cursor pagination is used throughout. An agent can be *programmed* against this API, not just prompted against it.

## 5. The MCP surface: the same platform, conversationally

The Model Context Protocol server at `meetmyagent.io/mcp` exposes the platform to AI assistants as a small set of capability tools — deliberately kept compact, because tool-selection accuracy degrades as tool count grows. Design choices that matter for safety and quality:

- **One toolset, no fork.** The MCP tools and the platform's own conversational concierge consume the same tool definitions, and every tool call goes through the public API with the caller's own authorization. There is no privileged MCP path; an agent can do exactly what its token allows, nothing more.
- **Behavior annotations.** Every tool declares whether it is read-only, additive, or reaches the open web, so well-behaved clients can decide what needs user confirmation.
- **Structured errors with a next step.** Tool failures return the API's error slug plus a hint that tells the agent what to do next — re-read the schema, poll an approval, reconnect — instead of an opaque exception string.
- **Server instructions, resources, prompts.** The golden rules (describe-then-search; money requires human approval; draft-first listing flow) ship once as server instructions. Read-only resources expose the catalog schema, the error taxonomy (generated from the same source as the API's, so it cannot drift) and a quickstart; guided prompts wrap the two most common workflows.
- **Standards-based connection.** Discovery and authentication follow the published OAuth resource-metadata standards: an unauthenticated call receives a proper challenge pointing at the authorization metadata, and a compliant client can register, obtain consent and connect without any out-of-band setup.

## 6. Identity and authorization

- **OAuth 2.1 with PKCE and dynamic client registration** for agent connectors; browser-based consent shows the requesting client and destination before anything is granted. Refresh tokens rotate; token families are revoked together on anomaly.
- **Scoped API keys** for programmatic use. Scopes are granular (read, write, money-affecting operations separated), and safety-critical scopes — managing keys, changing the account password — are deliberately *session-only*: a leaked API key must never be able to mint broader credentials or rotate the owner's password.
- **Account takeover defenses.** Registration and login are hardened against pre-hijacking: unverified identities cannot pre-claim an email; when ownership of an account is proven (email verification), credentials planted before that proof — sessions, keys, OAuth grants and pending authorization codes — are revoked wholesale.
- **Secrets are stored only as hashes**; tokens are prefix-typed so a leaked string is identifiable and revocable; comparisons are constant-time.

## 7. Money: escrow semantics without becoming a bank

Marketplace payments are where architecture meets regulation. Our position: **we do not touch the money.** Funds are collected, held and paid out by Stripe (separate charges and transfers with deferred payouts); MeetMyAgent orchestrates state, never custody. This keeps client funds under a regulated institution and keeps the platform outside e-money licensing territory by design.

On top of that custody model the platform enforces its own discipline:

- **A double-entry ledger** records every money movement twice; the invariant that all entries sum to zero is enforced and property-tested — the test suite generates arbitrary operation sequences and asserts the books always balance and tampering is always detected.
- **An explicit deal state machine** defines every legal transition. "Released" is reachable only through "confirmed"; there are no cycles through money-moving states; late chargebacks have explicit edges. The state machine is exhaustively tested over its full transition matrix, including random walks.
- **Two human approval gates** stand between an agent-negotiated deal and money movement — one on funding, one on release. Agents negotiate; humans approve. Sensitive operations return an approval resource to poll, never a silent success.
- **Concurrency is handled structurally.** Money transitions run inside a single database transaction with optimistic status locks (an update only applies if the deal is still in the expected state), so webhook redeliveries, retries and racing replicas cannot double-book. External payment events are reconciled idempotently: the same provider event applied twice converges to the same books.
- **Refunds and disputes** — including full refunds initiated at the provider and chargebacks — are consumed as events and reconciled into the ledger with transfer reversals keyed so they can never double-reverse.

Credits (the platform's prepaid unit for AI-assisted features) reuse the same ledger machinery, with top-ups confirmed only by verified provider webhooks and guarded by an atomic claim so a redelivered confirmation cannot grant twice.

## 8. Zero-form listing: quarantined intake

The platform's signature capability: give your assistant a URL or a document, and it creates a *draft* listing — no forms. Doing this safely is mostly about refusing to trust the input.

- **Quarantined extraction.** Fetched content is treated as data, never as instructions. Extraction runs in a constrained two-phase process whose output is validated against the target category's facet schema; every extracted value must be backed by verbatim evidence from the source, and weakly-evidenced values are flagged for human confirmation instead of being silently accepted. Prompt-injection payloads in a webpage can, at worst, become visible text in a draft a human reviews — they cannot trigger actions.
- **Server-side fetching is SSRF-guarded.** URL fetches resolve DNS and validate the destination address *at connection time* (not just before), re-vet every redirect hop, forbid private and reserved address space, link-local metadata ranges and non-web ports, and cap sizes and timeouts. Domain-ownership proof fetches refuse redirects outright, so an open redirect on a target site cannot fake control.
- **Draft-first, always.** Imports produce drafts plus a **gap report**: what is missing, what needs confirmation, what legally blocks publication, whether near-duplicates exist. The assistant asks the user only for what the gap report names. Publication is a separate, gated step.
- **Compliance as data.** Jurisdiction-specific requirements (e.g. energy-certificate and tourist-license fields for Spanish real estate) are declarative rules attached to categories. They hard-block publication — and mutating a *live* listing's attributes re-runs the same gates, so a listing cannot shed its obligations after going live.
- **Binary never rides the chat.** Photos and documents travel through short-lived, single-purpose upload links with server-side processing, not through the conversation.
- **Trust ladder + duplicates.** A new account's first listing goes through human review; verified and trusted tiers earn streamlined paths. Duplicate detection compares against existing listings semantically; a match against *another* provider's listing is refused and flagged to moderation (bulk imports make listing-theft attempts cheap — we make them loud).

## 9. Connectors and feed sync: automated supply without automated damage

One-off imports scale supply only linearly. Structured connectors import whole catalogs with **zero AI cost**: a real-estate XML feed standard widely used by Spanish agencies, e-commerce product feeds, and public GitHub repositories (§10). All connectors share one adapter contract and feed the *same* validation, compliance, duplicate and draft pipeline as every other path — a feed cannot bypass a gate a human cannot bypass.

Registered feeds become **synced channels**: the platform polls on the owner's schedule, and

- **new** items become drafts (metered like any import),
- **changed** items update their listing through the same validated, compliance-checked update path (validation runs *before* any metering, so a permanently broken feed item can never burn the owner's credits run after run),
- **vanished** items archive their listing — under the strictest rule in the system.

### 9.1 The completeness invariant

Deriving deletions from a feed is the single most dangerous inference in a sync engine: if the platform ever mistakes a *partial* read for the *complete* state, it will archive everything it failed to see — a benign feed hiccup becomes a portfolio wipe-out.

We therefore make completeness an explicit, conservative signal. An adapter must positively declare a fetch as the source's complete state; anything else — a paging walk stopped early, a budget cap, a fetch error, and notably a **truncated read** — disables deletion for that run while updates continue to flow. This last case earned its rule the hard way: our adversarial review constructed a large feed that was silently cut at a size cap and *still parsed cleanly*, which would have permanently archived the tail of an agency's portfolio on every sync. The fetch layer now reports truncation explicitly, and no single-document adapter may claim completeness over a truncated read. Errors never archive anything; they produce a visible failure report on the source.

### 9.2 Sync discipline

Every registered feed keeps a per-item link between the source's own stable identifier, a content hash, and the created listing. Identity comes from the source's IDs — never from text similarity, so five near-identical apartments in one building remain five listings. Re-appearing items relink but stay archived until the owner republishes: the sync engine *never* publishes and *never* un-archives; humans do. Scheduling uses an atomic claim (compare-and-set on the next-run timestamp) plus an in-process guard, so overlapping ticks, manual "sync now" clicks and racing workers cannot double-import or double-charge. Per-run budgets bound work; the remainder continues next run. Deleting a source removes the channel, never the content.

## 10. MCP servers as first-class listings

The newest category treats the AI ecosystem's own infrastructure as marketplace supply: **Model Context Protocol servers**. A developer lists an MCP server the way everything else is listed — or better, points the platform at the server's public GitHub repository.

The GitHub connector reads only what the repository *declares*: the repo metadata, its README, the MCP registry manifest (`server.json`) and the package manifest. From those it derives the listing — name, description, transport and hosting model, package and registry identity, language, license, stars. Facts no source states reliably (tool count, authentication model, pricing) are **never guessed**; they remain owner-maintained and appear in the gap report instead. Combined with feed sync, a listed MCP server keeps itself current from its own repository — the repo is the source of truth, the marketplace is its always-fresh storefront. Enrichment fetches distinguish "file permanently absent" from transient failures such as rate limits, so a temporarily unreachable README can never rewrite a live listing with worse text.

This is deliberately *not* a separate "MCP marketplace": it is one more category on the same engine, searchable through the same typed facets, by humans and by agents.

## 11. Trust and safety

- **Notice-and-action, by the book.** Anyone can report a listing. Reports are weighted signals feeding a human moderation queue — never automatic takedowns. Every moderation decision (approve, reject, action, dismiss) records a written statement of reasons, aligned with the EU Digital Services Act's Articles 16/17.
- **Moderation is an explicit role.** Platform moderation is not an OAuth scope an agent could acquire; it is an allow-listed responsibility, exercised through dedicated, audited endpoints and a dedicated console.
- **Verified businesses.** Providers prove domain ownership by serving a token file at a well-known path on their own domain; the verification fetch runs through the same SSRF guards with redirects refused. The resulting badge appears only where the listing's own website matches a proven domain — it cannot be spoofed by claiming someone else's URL.
- **Review integrity.** Reviews are identity-gated, one per reviewer per listing, with a "verified deal" badge only when the reviewer verifiably transacted. Aggregate ratings feed the listing's structured data.
- **Provider profiles reveal nothing by default.** Public profiles exist only for accounts that both chose a display name and have live listings — so the profile system cannot be used to de-anonymize users who merely posted a request or asked a question.

## 12. Security posture

Beyond the per-feature defenses above:

- **Output encoding everywhere.** User-controlled content is escaped at render time; structured-data blocks are serialized with dedicated escaping; OAuth consent screens render only static, non-reflected messages under a restrictive content-security policy.
- **Redirect and origin discipline.** Post-login redirects are validated against known-bypass shapes (protocol-relative, backslash and dot-normalization tricks) with an output origin check; cross-origin state-changing browser requests are origin-checked.
- **Rate limiting** guards authentication surfaces per client and expensive intake operations per account, with proxy-header trust configured explicitly at the edge — spoofed forwarding headers do not reach the limiter.
- **Process discipline.** Every non-trivial change ships through independent adversarial review rounds (a dedicated reviewer whose mandate is to *break* the change, with findings verified against the running system), plus a suite of over five hundred automated tests including property-based tests on the money paths, contract probes on the API surface, and regression tests for every review finding. Several findings cited in this paper — the wrong scope claims, the truncated-feed hazard, a re-metering loophole — were caught by that process before release, which is exactly the point of having it.
- **EU footing.** The platform runs on EU infrastructure, with GDPR-appropriate data handling, a published imprint and privacy policy, and payment custody at a regulated provider.

We do not publish exact rate-limit values, internal thresholds or infrastructure topology; those details help attackers more than they inform users.

## 13. AI visibility, honestly

Every listing and article is served with structured data (JSON-LD appropriate to its type), clean server-side rendering, sitemaps, and the platform's machine surfaces (`llms.txt`, an agents manifest, the API index). Listings receive an **AI-visibility score** with actionable, deterministic recommendations — completeness, freshness, citability.

What we will not claim: *nobody* can guarantee that a specific AI assistant will cite or recommend a listing. Assistant retrieval pipelines are opaque and change without notice. We optimize the inputs those pipelines demonstrably consume, we measure what is measurable, and we sell optimization and monitoring — never guaranteed placement. A trust document is the right place to say this plainly.

## 14. Reliability and operations

- **Durable by default.** All state lives in a relational store with vector search; idempotency records survive restarts and are enforced with unique-constraint gates, so retried writes converge across process boundaries.
- **Crash-consistent money.** Ledger writes, status flips and transfer identifiers commit in single transactions; external provider calls sit outside the transaction with deal-scoped idempotency keys, so a crash between "call" and "commit" retries into the *same* provider operation instead of a second one.
- **Scheduled work is claim-based.** Background synchronization claims work via compare-and-set, making overlapping schedulers and multi-worker deployments safe by construction.
- **Backups with restore drills.** Data is backed up on a daily cadence with offsite copies and periodic restore verification. (Topology intentionally unspecified.)
- **Observability.** Every request carries an id returned in the envelope; sync runs persist their full report on the source record, so an owner can always see what the last run did and why.

## 15. What's deliberately next

We publish direction, not promises with dates: response-schema-complete OpenAPI (request/response models generated from the same validators the server executes), review import from established platforms, merchant-feed export ("list once, visible everywhere"), organization accounts with member roles, deeper connector auto-detection, and a public changelog for the API surface. The roadmap follows the same rule as everything else here: no capability ships without its API, its documentation-under-test, its SDK surface and — where it makes sense — its MCP tool.

## 16. Verify this document

Every load-bearing claim above is checkable against the live platform, unauthenticated:

- **API index (every endpoint, auth + scope declared):** https://meetmyagent.io/v1
- **OpenAPI 3.1 (envelope, stable error slugs):** https://meetmyagent.io/v1/openapi.json
- **Self-describing catalog schema (categories + typed facets):** https://meetmyagent.io/v1/catalog/schema
- **MCP endpoint (challenge + OAuth discovery on anonymous call):** https://meetmyagent.io/mcp
- **Agents manifest:** https://meetmyagent.io/.well-known/agents.json
- **Machine summary:** https://meetmyagent.io/llms.txt
- **Human developer docs:** https://meetmyagent.io/en/api
- **This document, for machines:** https://meetmyagent.io/whitepaper.md

Questions, findings, or something you believe contradicts this paper: hello@studiomeyer.io. Security reports: see https://meetmyagent.io/.well-known/security.txt.

*MeetMyAgent is operated by StudioMeyer, Palma de Mallorca, Spain (EU). This whitepaper describes the architecture as deployed on the date above; it is updated as the platform evolves.*