How to use MCPs

Connect an app

Unoic uses a remote Streamable HTTP MCP endpoint. Your client must support remote MCP and an authentication method below. Adding the URL to this guide does not install a connection in your AI app.

1. Create a connection in Integrations. Give each app a recognizable name. Choose its permissions, set hourly limits, and save it with Create connection.
2. Grant the content it needs. For video tools, select the relevant video or media banks. Make each raw video shareable in Videos available to connections; interactive source videos must already be published in Studio.
3. Add the MCP URL in your client. Use its remote MCP or connector settings, then select the sign-in or token method it supports.
4. Check the connection. Ask the client to run get_capabilities. Check the returned offerings before requesting an output.

A Studio login session manages connections. The MCP client uses its own OAuth authorization or the connection’s issued bearer token.

Give these instructions to an agent after the MCP connection is available in its client.

1. Call get_capabilities first. Use its exact schemas and supported profiles; certified inventory can run out between discovery and reservation.
2. Choose a fresh idempotencyKey for each intended output. After a transport failure, retry with the same key and parameters. A different request needs a different key.
3. Save the returned jobId and call get_job at a sensible interval. queued and running are in progress. Stop at ready, needs_review or failed.
4. Read artifact.reviewStatus and artifact.warnings. Surface review concerns, then return the real hosted url, embedHtml or asset download link. Never invent IDs or links.

Tools and games

The connection exposes the following tools. Its granted permissions determine which calls succeed.

Games available through create_game

Word Searchword-search

Supply 1–32 reviewed words, or a theme for AI vocabulary. English, Hindi and Gujarati; grids from 5 × 5 to 24 × 24. Explicit words take precedence over a theme.

Kakurokakuro

Choose a listed size and difficulty profile. Bounded generation can return NO_MATCH; it never substitutes another profile.

Calcudokucalcudoku

Choose a listed size, tier, arithmetic mode and load. Ratings are provisional; bounded generation can return NO_MATCH.

Futoshikifutoshiki

Reserves an existing certified puzzle. Availability changes with use; check inventory before requesting a profile.

Hidatohidato

Reserves an existing certified puzzle in Easy or Medium. Hard and Expert are unavailable.

Cryptogramcryptogram

Create a substitution puzzle from your statement, keywords and teaching notes. Choose guided, standard, hard or expert. Authored content needs review; generation does not fact-check the statement.

Find Differencesfind-differences

Supply two JPEG images, 1–16 matching difference regions and a question for each difference. Uses your annotations; it does not generate images or detect differences.

Diagrams support en, hi and gu, with sizes 720x720, 1280x720 and 720x1280. Each publication includes SVG and opaque white JPEG exports. Automated review can flag an output for human review; a pass is not a factual guarantee.

compose_video adds supplied quiz or sandboxed lab checkpoints and optional captions to an eligible shared video. It publishes a new lesson without changing the source. It does not edit, splice or render video bytes, fetch arbitrary video URLs, or generate lesson content with AI.

Request examples

These are the params objects for MCP tools/call, not standalone HTTP request bodies. An MCP SDK or connected client handles initialization and the protocol envelope.

{
  "name": "create_game",
  "arguments": {
    "idempotencyKey": "science-word-search-001",
    "parameters": {
      "gameId": "word-search",
      "words": [
        "EARTH",
        "WATER",
        "LIGHT"
      ],
      "rows": 12,
      "cols": 12,
      "language": "en"
    }
  }
}

{
  "name": "generate_svg",
  "arguments": {
    "idempotencyKey": "right-triangle-diagram-001",
    "parameters": {
      "prompt": "Draw a clear right triangle with side lengths 3, 4 and 5. Mark the right angle. Use English labels.",
      "title": "A 3–4–5 right triangle",
      "size": "720x720",
      "language": "en"
    }
  }
}

{
  "name": "create_game",
  "arguments": {
    "idempotencyKey": "photosynthesis-cryptogram-001",
    "parameters": {
      "gameId": "cryptogram",
      "statement": "Plants use sunlight to make sugar and release oxygen.",
      "keywords": [
        "sunlight",
        "sugar"
      ],
      "concept": "Photosynthesis",
      "alternative": "Evaporation",
      "explanation": "Photosynthesis uses light energy to make sugars.",
      "preset": "standard"
    }
  }
}

{
  "name": "search_videos",
  "arguments": {
    "query": "fractions",
    "sourceType": "raw",
    "limit": 10
  }
}

{
  "name": "get_video_embed",
  "arguments": {
    "idempotencyKey": "fractions-video-001",
    "parameters": {
      "sourceType": "raw",
      "videoId": "<id returned by search_videos>"
    }
  }
}

{
  "name": "compose_video",
  "arguments": {
    "idempotencyKey": "fractions-checkpoint-001",
    "parameters": {
      "sourceType": "raw",
      "videoId": "<id returned by search_videos>",
      "title": "Fractions checkpoint",
      "durationSeconds": 60,
      "cues": [
        {
          "id": "checkpoint-1",
          "atSeconds": 30,
          "kind": "quiz",
          "questions": [
            {
              "id": "question-1",
              "prompt": "Which fraction is equal to one half?",
              "options": [
                {
                  "id": "option-a",
                  "text": "2/4"
                },
                {
                  "id": "option-b",
                  "text": "1/4"
                }
              ],
              "correctOptionId": "option-a",
              "explanation": "Two quarters cover the same amount as one half.",
              "onCorrect": {
                "mode": "continue",
                "targetSeconds": null
              },
              "onIncorrect": {
                "mode": "jump",
                "targetSeconds": 20
              }
            }
          ]
        }
      ]
    }
  }
}

Permissions and sharing

catalog:read is included in every connection. Enable games:create for games, assets:create for diagrams, and assets:read to request their export links. Video tools require videos:read, an explicit bank grant and an eligible source.

OAuth authorization records what the owner approved. Removing a permission or bank takes effect immediately. Adding new access to a connection does not expand an existing OAuth grant; reconnect and approve the updated access. Queued jobs also retain the permissions and banks available when they were submitted.

A static bearer token follows the connection’s current settings. Changes to its permissions, banks or active state affect subsequent calls. Treat anyone holding this token as able to use that connection.

Published links are unlisted. Anyone with a link can open it while it remains active. Revoking a publication, pausing a connection, removing the relevant permission or bank, or withdrawing a video source permanently withdraws affected existing links. Restoring access permits new publications; it does not revive old ones.

Keep tokens in trusted clients or server-side secret storage. Never paste them into iframe HTML, public source code or an end-user browser bundle. Already downloaded or buffered content cannot be recalled.

Limits and delivery

2 active jobs

At most two queued or running jobs per owner across all connections.

60 games / hour

Owner-wide rolling hourly ceiling. A connection’s game limit may be lower.

10 diagrams / hour

Owner-wide rolling hourly ceiling. A connection’s image limit may be lower.

120 requests / minute

Per connection across MCP traffic, including discovery and job polling.

50 MiB video sources

Eligible saved MP4, WebM and Ogg video files. Source access is checked again at publication and delivery.

Admitted jobs count toward hourly creation limits even if they later fail. Repeating an unchanged request with its original idempotency key returns the same job. Increasing a connection’s limit does not raise the owner-wide ceiling.

Jobs run independently of the client request. Closing your client does not cancel an admitted job. Game and video results include hosted players and iframe HTML; diagrams include download links. Progress in practice games stays in that browser. These games are not secure examination scoring.

Troubleshooting

A tool failure has isError: true and an error object with code, message and retryable. A failed job exposes its error through get_job.

Sign-in or token rejected

Check the URL, active connection and authentication method. A replacement bearer invalidates the older one. Complete OAuth sign-in again if authorization has expired or changed.

FORBIDDEN or empty video results

Check the required permission, selected banks and source sharing. A bank grant alone does not make a raw video shareable. After expanding OAuth access, reconnect.

INVALID_INPUT / PROFILE_UNAVAILABLE

Read get_capabilities again and match the exact schema and profile. Do not silently change the user’s requested size, difficulty or content.

NO_MATCH / no certified inventory

Bounded generation did not find a suitable puzzle, or the requested catalog stock is exhausted. Explain the result and choose an available profile with the user. A seed does not guarantee success.

IDEMPOTENCY_CONFLICT

The key already belongs to different parameters. Use the original request to retrieve that job, or a new key for a new intended output.

CONCURRENCY_LIMIT / QUOTA / OWNER_QUOTA

Let existing jobs finish or wait for the rolling hourly window. Check the connection’s lower limit if applicable.

RATE_LIMITED / QUEUE_UNAVAILABLE

For rate limits, wait a minute. If the queue is unavailable, the job may already be saved; retry the same key and parameters. Avoid generating duplicate outputs.

needs_review or provider failure

Inspect warnings before teaching or sharing. For an uncertain provider outcome, do not automatically create another paid request. A deliberate new attempt needs a new key.

A published link returns 404

It may have been revoked, its connection paused, its permission or bank removed, or its source withdrawn. Restoring access requires creating a new publication.