Get your service listed

Use these steps to publish and verify the files on your live domain — the prompt covers every format above.

1. 1

   Publish discovery files

   Paste this into your coding agent (Claude Code, Cursor, Codex) from your product's repo. It inventories your integration surfaces, writes /.well-known/integrations.json, and publishes every open standard that applies — OpenAPI spec, MCP server card, llms.txt, and the rest.

   prompt — add my product to registry.rafads.com copy

   You are working inside my product's repository. Goal: make my product discoverable on registry.rafads.com by publishing discovery files on my own domain — both the open standards it reads and its own /.well-known/integrations.json declaration. Publish every format that applies to my product; they are complementary, not alternatives. Derive every value from THIS repo and its docs. Never invent endpoints, specs, or auth. Leave out any file or surface my product does not actually have.
   
   # 1. Inventory the integration surfaces
   
   Read the codebase, README, and docs to find each way an agent could integrate with my product, and how each authenticates:
   - HTTP/REST API — base URL, and whether an OpenAPI/Swagger spec exists in the repo or is served somewhere.
   - MCP server — the connect URL and transport (streamable-http or sse), if one ships.
   - GraphQL API — the endpoint URL, and SDL/introspection availability.
   - CLI — the command name and how it installs (npm/pypi/oci/brew).
   For each surface, determine the auth: none (public), or the credential(s) needed and exactly how they ride the request (header name + scheme, or query/body param, or a CLI login/env var).
   
   # 2. Author /.well-known/integrations.json
   
   Write ONE file at /.well-known/integrations.json on my production domain with EVERYTHING inline — there is no index/reference layout. The file holds version + summary + a shared credentials map + a "surfaces" list of full surface objects. Credentials are defined once in the top-level "credentials" map and referenced from each surface's auth by id.
   
   Serve it as application/json, publicly cacheable (e.g. Cache-Control: public, max-age=3600).
   
   File shape (v3):
     { "version": 3, "summary"?: string, "credentials"?: { [id]: Credential },
       "surfaces"?: Surface[] }
   
   Credential (defined once in "credentials", keyed by id, referenced from a surface's auth):
     { "type": "api_key"|"bearer"|"basic"|"oauth2"|"oauth2_cc"|"jwt"|"custom"|...,
       "label": string,                 // human name, e.g. "Acme API key"
       "generateUrl"?: string,          // where the user mints it
       "setup": string,                 // markdown: how to get it, gotchas
       "fields"?: { [name]: { "secret"?: boolean, "description"?: string } } }  // only for multi-part secrets
   
   Surface (discriminated on "type"). Common fields on every surface:
     "slug": string,                    // stable url segment, e.g. "acme-api"
     "name": string,                    // display name
     "docs"?: string,                   // human docs URL
     "basis": { "via": "declared", "source": "https://MY_DOMAIN/.well-known/integrations.json" },
     "auth": AuthStatus
   Per-type extra fields:
     http:    "spec"? (OpenAPI doc URL), "url"? (base URL)
     graphql: "url"? (endpoint), "spec"? ("introspection" or SDL URL)
     mcp:     "url"? (connect endpoint), "transports"?: ["streamable-http"] | ["sse"]
     cli:     "command"?: string, "packages"?: [{ "registryType": "npm"|"pypi"|..., "identifier": string, "runtimeHint"?: "npx"|"uvx" }]
   
   AuthStatus is one of:
     { "status": "none",    "basis": { "via": "declared", "source": "https://MY_DOMAIN/.well-known/integrations.json" } }   // confirmed public
     { "status": "unknown" }                                                                                               // not determined
     { "status": "required", "entries": [ AuthEntry ] }  // entries are OR alternatives; at least one works
   AuthEntry:
     { "use": [ { "id": "<credential id>", "mechanics": Mechanics } ],   // multiple uses are AND'd (sent together)
       "basis": { "via": "declared", "source": "https://MY_DOMAIN/.well-known/integrations.json" } }
   Mechanics (how ONE credential binds), pick the matching shape:
     { "source": "http", "in": "header", "headerName": "Authorization", "scheme": "Bearer" }
     { "source": "http", "in": "query",  "paramName": "api_key" }
     { "source": "cli",  "command"?: "acme login", "env"?: ["ACME_API_TOKEN"] }
     { "source": "spec", "scheme": "<securityScheme name from the OpenAPI doc>" }
     { "source": "well-known" }   // MCP OAuth resolvable from the surface url via RFC 9728/8414
     { "source": "unknown" }
   
   Rules:
   - Replace MY_DOMAIN with my real production host everywhere.
   - Every surface's basis.source and every auth basis.source must be my integrations.json URL (https://MY_DOMAIN/.well-known/integrations.json).
   - Only include surfaces that exist. Omit "credentials" / "surfaces" entirely if there are none.
   - The file must parse as strict JSON and validate against the v3 shape above, or registry.rafads.com silently ignores it.
   
   # 3. Publish the open standards that apply
   
   registry.rafads.com reads these alongside integrations.json — publish every one my product qualifies for:
   
   - OpenAPI: if my product has an HTTP API and an OpenAPI/Swagger spec exists (or can be generated from the code), serve it at /openapi.json (registry.rafads.com also probes /swagger.json, /api/openapi.json, /v1/openapi.json, /api/schema/ — /openapi.json is the canonical one). Serve as application/json, publicly cacheable. If a spec route already exists, just make sure one of those paths resolves to it.
   - MCP server card: if my product ships an MCP server, serve /.well-known/mcp/server-card.json with at least { "url": "<mcp connect endpoint>" } and, if the server needs auth, "authentication": { "type": "oauth2", "authorization_server"?: "<as url>" }. application/json, publicly cacheable.
   - llms.txt: if my docs have a good plain-language overview, serve /llms.txt summarizing the product and linking the key docs pages.
   - api-catalog (RFC 9727): if I publish more than one API surface, serve /.well-known/api-catalog as a linkset pointing at my API base URLs, OpenAPI docs, and MCP endpoints.
   - OAuth protected resource (RFC 9728): if my API or MCP endpoint is protected by OAuth, serve /.well-known/oauth-protected-resource with the resource id and authorization server(s).
   - Agent card: if my site publishes an agent-facing identity, serve /.well-known/agent-card.json.
   - Agent skills: if my product ships reusable agent skills or task instructions, serve /.well-known/agent-skills/index.json listing them.
   
   Skip any of these that don't apply — only publish files backed by something real in this repo.
   
   # 4. Verify
   
   Print copy-paste curl commands to confirm EVERY file you published resolves on my live domain with the right content-type (JSON files as application/json), e.g.:
     curl -sS -D- -o/dev/null https://MY_DOMAIN/.well-known/integrations.json
     curl -sS https://MY_DOMAIN/.well-known/integrations.json | jq .
     curl -sS -D- -o/dev/null https://MY_DOMAIN/openapi.json                 # if you published one
     curl -sS https://MY_DOMAIN/.well-known/mcp/server-card.json | jq .      # if you published one
     ...and one per standard from step 3 that you published.
   
   Then tell me: open https://registry.rafads.com/MY_DOMAIN/ and click "Map integration surface" to publish the listing.

   I already have an OpenAPI spec or MCP server

   prompt — expose an existing spec / MCP server copy

   You are working inside my product's repository. I already have an OpenAPI spec and/or an MCP server. Expose them at the conventional paths registry.rafads.com probes. Use the real files in this repo; do not invent anything.
   
   1. If I have an OpenAPI/Swagger document, serve it at /openapi.json on my production domain, as application/json and publicly cacheable (registry.rafads.com also checks /swagger.json, /api/openapi.json, /v1/openapi.json, /api/schema/ — /openapi.json is canonical). If a spec route already exists, just make one of those paths resolve to it.
   
   2. If I ship an MCP server, serve /.well-known/mcp/server-card.json with at least:
      { "url": "<my MCP connect endpoint>", "authentication"?: { "type": "oauth2", "authorization_server"?: "<as url>" } }
      as application/json, publicly cacheable. Fill "authentication" only if the server needs it; derive the values from the repo.
   
   3. Print curl commands to verify each path resolves on my live domain with a JSON content-type. Then tell me to open https://registry.rafads.com/MY_DOMAIN/ and click "Map integration surface".
   
   If you also author /.well-known/integrations.json, put everything in that one file: version + summary + a shared "credentials" map + a "surfaces" list of full surface objects. There is no index/reference layout — no separate per-surface files. Credentials are defined once in "credentials" and referenced from each surface's auth by id.

2. 2

   Verify

   Check the files resolve on your live domain and return JSON. The agent prints these; run them yourself to confirm (swap in your host):

   curl -sS https://your-domain.com/.well-known/integrations.json | jq .
   curl -sS https://your-domain.com/openapi.json | jq .                    # if published
   curl -sS https://your-domain.com/.well-known/mcp/server-card.json | jq . # if published

   The file must parse as strict JSON and be served with an application/json content-type — an HTML 404 or a JSON {"error":"Not Found"} won't be trusted.

3. 3

   Get discovered

   Open https://registry.rafads.com/{your-domain}/ and click Map integration surface. The run reads your files, refreshes the conventions scorecard and discovered surfaces, and your listing is live immediately.