Connect your game.

1. Connect your coding agent

Configure an HTTP MCP connection to /api/mcp/developerson your Idealite environment. No login, API key or Authorization header is needed. Initialize, list tools, then call read_creator_guide. Public topic lookup and game submission use ordinary server operations, with no Idealite AI calls. Per-caller and shared rate limits apply.

Your agent chooses topics. Idealite validates the published metadata and records a pending submission. Admin approval is required before a game becomes eligible for shared recommendations.

• read_creator_guide — Read Idealite's public game publishing guide. No login or model calls.
• search_topics — Search public canonical topics by name, alternate name or description. Returns IDs and hierarchy; choose relevant IDs yourself. No AI calls or topic creation.
• submit_game — Submit a public HTTPS game URL for catalog review. Resubmit the same URL after updating its metadata to propose a new revision. Existing approved catalog data stays live until approval. Does not grant ownership or save to a user library.
• get_game_submission — Get public validation feedback and pending/approved/rejected status by submission ID.

2. Select topics, publish and submit

1. Create a game in your own repository. Keep credentials and private source notes out of published files.
2. Connect to /api/mcp/developers without an Authorization header. Call search_topics with query (2–120 characters), optional direct parentId, limit (1–20) and offset. Search names, aliases and descriptions; inspect returned hierarchy and choose appropriate tagId values yourself. No Idealite model calls or topic creation. Try alternate wording if no topic matches; missing topics require operator review.
3. Use manifest schemaVersion 2 for rich discovery. Set experience.topics to {status: "resolved", selectionSource: "publisher", tagIds: [canonical IDs from search_topics]}. Do not invent IDs, contentHash or resolverVersion. This publisher-selection extension is supported by Idealite; external Studio contract validators must also support it before use. Public submissions require at least one game topic. The example leaves topics unresolved as placeholders to replace.
4. Publish public HTTPS HTML and a same-origin JSON file. Add exactly one <meta name="idealite:metadata" content="./idealite-game.json"> to the HTML head. Standard OpenGraph tags can supply title/description previews. The linked JSON is the discovery contract.
5. Publish at your normal public game URL and call submit_game with only url. A versioned URL is not required. Idealite fetches the hosted manifest and validates shared topic IDs. Submission does not grant ownership, save to a learner library, or approve recommendations. No API key or Idealite model call is required.
6. Retain submissionId and use get_game_submission to read revision, pending/approved/rejected status and public feedback. Unchanged metadata returns the same revision/status. After publishing changed metadata, resubmit the same URL: this proposes a new pending revision. Existing approved catalog data stays active until the update is approved; rejection leaves it intact. Approval returns a resourceId and enables catalog eligibility, not guaranteed recommendation delivery.
7. Verify the game can actually launch. Metadata declarations do not prove device compatibility, grading quality or educational accuracy. Registration, recommendation delivery and card integration are separate acceptance checks.

{
  "url": "https://your-domain.example/"
}

Example arguments for submit_game. Replace the example URL. The same services are available as JSON APIs: GET /api/developers/topics?query=genetics, POST /api/developers/games, and GET /api/developers/games/<submissionId>.

3. Add discovery metadata

<meta name="idealite:metadata" content="./idealite-game.json">

• Replace the example provider/game identities, title, version, concepts, experience and launch entries with your own. The reserved idealite-game-studio provider is limited to recognized Studio hosting domains.
• Studio's publisher returns catalogUrl (the root share/submit URL) and releaseUrl (the preserved /v/version/ build); legacy url remains the release URL. The updated Studio host redirects the root to its latest committed release. Deploy both components before relying on this. External publishers may keep their ordinary URL and are not required to host immutable versions for catalog listing.
• Catalog identity and saved-card identity differ. Idealite stores catalogUrl separately from a recognized Studio releaseUrl. Optional card support requires a preserved build and specific challenge inputs. Do not claim card compatibility from catalog submission alone.
• Full-game topics describe the game; activity topics describe that activity and must not inherit all parent topics by default. Creators do not need to enumerate or tag every internal question to register the game.
• launchPath identifies an independently launchable HTML activity. null describes a section without an independent entrypoint. Existing discovery activities are not automatically saveable cards.
• Publish metadata as application/json, HTML as text/html. Submitted and metadata URLs must be public HTTPS, no credentials/query/fragment. Metadata must stay same-origin. The importer rejects invalid declarations rather than silently downgrading them.

{
  "schemaVersion": 1,
  "providerId": "lessons.example",
  "resourceType": "game",
  "manifest": {
    "schemaVersion": 2,
    "gameKey": "camera-lab",
    "title": "Camera Lab (contract example)",
    "version": "0.2.0",
    "entrypoint": "index.html",
    "supportedConcepts": [
      "camera.aperture"
    ],
    "supportedModes": [
      "full-tour"
    ],
    "supportedDifficulties": [
      "beginner"
    ],
    "discovery": {
      "experience": {
        "summary": "Explore how aperture changes the amount of light entering a camera.",
        "audience": "Introductory photography students",
        "learningObjectives": [
          "Explain how aperture size affects incoming light."
        ],
        "scope": "lab",
        "estimatedMinutes": 10,
        "topics": {
          "status": "unresolved"
        },
        "requiredActions": [
          "adjust",
          "confirm"
        ],
        "inputProfiles": [
          {
            "id": "touch",
            "label": "On-screen controls",
            "inputs": [
              "touch"
            ],
            "actions": [
              "adjust",
              "confirm"
            ],
            "targets": [
              "mobile-browser"
            ],
            "testedTargets": []
          }
        ],
        "runtimeRequirements": [],
        "entryMode": "explore"
      },
      "activities": [
        {
          "id": "aperture",
          "title": "Aperture challenge",
          "conceptIds": [
            "camera.aperture"
          ],
          "supportedDifficulties": [
            "beginner"
          ],
          "launchPath": "activities/aperture/index.html",
          "experience": {
            "summary": "Adjust aperture to reach a target amount of incoming light.",
            "audience": "Introductory photography students",
            "learningObjectives": [
              "Explain how aperture size affects incoming light."
            ],
            "scope": "challenge",
            "estimatedMinutes": 2,
            "topics": {
              "status": "unresolved"
            },
            "requiredActions": [
              "adjust",
              "confirm"
            ],
            "inputProfiles": [
              {
                "id": "touch",
                "label": "On-screen controls",
                "inputs": [
                  "touch"
                ],
                "actions": [
                  "adjust",
                  "confirm"
                ],
                "targets": [
                  "mobile-browser"
                ],
                "testedTargets": []
              }
            ],
            "runtimeRequirements": [],
            "entryMode": "focused-challenge"
          }
        }
      ]
    }
  }
}

Optional: design saveable challenges

Web prototype, protocol version 1: one single-choice question per challenge; reviewed preserved Studio releases only. Optional for catalog listing.

• Expose only one independently answerable task per saveable challenge, with one graded outcome. Preserve the interface by sharing a component between game and independent challenge mode.
• Use a stable challenge ID plus pinned game version and frozen question inputs when generated. Reopening must not choose a new random question or require previous rounds.
• Publish a separate JSON export under the same preserved release, served as application/json. Link exactly one idealite:challenges meta tag from the standalone activity's HTML head. Do not add fields to the discovery manifest. Match providerId, gameKey and version; activityId and launchPath must identify a reviewed challenge-scope entry. Export at most 20 uniquely identified challenges, 2–8 distinct choices and one matching correctOptionId per question. Include complete context, explanation and objective. Configuration is a bounded object of primitive values (at most 20 keys); no secrets or learner state.
• The web prototype entry is /games/<resourceId>. Idealite shows Save challenge only after the exported question's bridge reports readiness. Explicit saving creates/reuses an owned quiz_item artifact and game_challenge card, preserves the version/configuration/presentation, and queues Idealite's existing question-topic resolution. Authors need not tag each question.
• Listen for initialization only from window.parent, validate the exact version/challenge/configuration, and pin its origin and instanceId. In review mode, open the exact frozen question immediately without prior rounds or post-answer gameplay. Send ready after it is answerable. Send answer with selectedOptionId once, echoing version, challengeId and instanceId, using postMessage(message, pinnedParentOrigin). Do not send correct booleans as grading authority. Idealite checks the answer against its saved definition and commits a review only on Continue. No user identity, credentials, or schedule commands cross the bridge.
• The host validates event.source, exact game origin, message schema, instanceId, challengeId and answer IDs, and ignores duplicate/late messages. Reload creates a fresh instance. The creator must use an exact targetOrigin and ignore unsupported messages. An iframe does not prove grading correctness: independently verify the published export matches the visible question.
• If browsing leaves the singular question for ordinary gameplay, send idealite.challenge.unavailable with the same envelope. The host disables saving until ready is sent again for that question. Review mode should stay on its question after answering.
• Card reviews retain the base schedule. Deck membership adds separate scheduling under the deck's algorithm. Neither saving nor normal play automatically creates learning-map goal evidence; goal-linked completion is separate.

<meta name="idealite:challenges" content="../../idealite-challenges.json">

{
  "schemaVersion": 1,
  "game": {
    "providerId": "idealite-game-studio",
    "gameKey": "camera-lab",
    "version": "0.2.0"
  },
  "challenges": [
    {
      "id": "aperture",
      "activityId": "aperture",
      "title": "Aperture challenge",
      "standalone": true,
      "launchPath": "activities/aperture/index.html",
      "configuration": {
        "seed": 42,
        "target": 2
      },
      "question": {
        "prompt": "Which opening lets in more light?",
        "context": "Two equally lit openings: A is larger than B.",
        "objective": "Relate aperture size to incoming light.",
        "options": [
          {
            "id": "larger",
            "label": "A"
          },
          {
            "id": "smaller",
            "label": "B"
          }
        ],
        "correctOptionId": "larger",
        "explanation": "The larger opening admits more light."
      }
    }
  ]
}

{
  "type": "idealite.challenge.init",
  "version": 1,
  "instanceId": "11111111-1111-4111-8111-111111111111",
  "challengeId": "aperture",
  "mode": "review",
  "configuration": {
    "seed": 42,
    "target": 2
  }
}

{
  "type": "idealite.challenge.ready",
  "version": 1,
  "instanceId": "11111111-1111-4111-8111-111111111111",
  "challengeId": "aperture"
}

{
  "type": "idealite.challenge.answer",
  "version": 1,
  "instanceId": "11111111-1111-4111-8111-111111111111",
  "challengeId": "aperture",
  "selectedOptionId": "larger"
}

{
  "type": "idealite.challenge.unavailable",
  "version": 1,
  "instanceId": "11111111-1111-4111-8111-111111111111",
  "challengeId": "aperture"
}

A game is the experience. A retained card is one specific question. A deck groups cards and adds its own review schedule while each card keeps its base schedule. Learning-map goal evidence is separate. No automatic playthrough logging is required.

Troubleshooting

rate_limited

Respect Retry-After. Public API and MCP share per-caller and global Redis limits, with stricter submission limits.

credentials_not_supported

Connect to /api/mcp/developers without Authorization. Existing private learner/admin tools remain on /api/mcp and require credentials.

invalid_arguments

Follow the tool's input schema. URL registration accepts no caller user ID, metadata object, or topic override.

unavailable_topics

Select only shared canonical IDs returned by search_topics. Unknown, private or deleted IDs are rejected. Unresolved activity topics may stay unresolved; the full game needs a topic.

metadata_changed

The site changed after submission. Submit the same game URL again, then have an admin review the current revision.

revision_changed

The candidate changed while it was being reviewed. Admins must reload the pending record and send its current revision with their decision.

service_unavailable

The service may need its Redis configuration or submission table schema update. Retry later; no paid resolver fallback is used.