MCP Server Setup

Need help getting this into your workflow fast?

Email support@game-oracle.com and we'll help you get it set up.

Game Oracle provides an MCP server, included with every Business account, so your AI agents and chatbots can query market intelligence directly. Not on Business yet? See pricing.

Access Requirements

  • Active business role subscription.
  • At least one active Business API key.
  • MCP endpoint URL: https://game-oracle.com/api/business/v1/mcp
  • Authentication header: Authorization: Bearer go_biz_<your_key>

Available Tools

Every tool mirrors a REST endpoint and accepts the same arguments (see the API documentation).

Search (search:read)

  • search_by_title: Games most similar to a Steam appId (default 1000 nearest), with optional filters and attributes.
  • search_by_description: Games most similar to a free-text query.
  • search_by_image: Games visually similar to up to 5 images, given as imageUrls (public https) and/or inline images: [{ data, mimeType }] (base64).
  • search_by_attributes: Structured search over any catalogue field, sortable.
  • search_combined: Layered search fusing title, description and image sources.
  • list_search_fields: The fields attributes and sort accept, the enumerated filters options, and pointers to the vocabulary tools below.

Reference data (any active key, free)

Use these first: they return the exact strings the search and Concept Compass tools validate against, so an agent never has to guess a tag or an engine name.

  • list_tags: Every Steam tag the catalogue uses — all_tags, grouped genres and themes, visuals, player_support, nsfw, steam_features — for attributes.meta_tags and filters.includeTags / excludeTags.
  • list_field_values: Distinct values of one low-cardinality field, most common first: field is one of game_engine, age_category, publication_era, controller_support, supported_languages.
  • list_segment_options: Everything search_segments accepts — dimensionalities, the live subcategory list per dimensionality, sortBy keys, exclusion flags and range parameters.
  • list_concept_options: The tag lists, enums, defaults and limits create_concept_project validates against (visualStyle, artStyle, playerPerspective, themesGenres, scope, featureIds).
  • list_features: Search the ~470 game design features (“building blocks”: mechanics, systems, settings, presentation) by q and category, 50 per page. Their ids are what create_concept_project takes as featureIds.

Games (games:read)

  • get_game_report: The full report for one app_id.
  • start_game_reports_job: Batch reports for up to 100 appIds (returns a job).

Game Gap (gaps:read)

  • search_segments: Market segments with the same filters as the app, or specific clusterIds.
  • get_segment_report: The full report for one cluster_id.
  • start_segment_reports_job: Batch reports for up to 100 clusterIds (returns a job).

Outliers (outliers:read)

  • list_outliers: listType of upcoming_games or released_games.

Concept Compass (concepts:write)

  • create_concept_project: Create a project from the wizard inputs and start its report (returns a job). Optional featureIds (1–5, from list_features) name the concept’s core features.
  • get_concept_report: The full report for a projectId, or its generation status.
  • update_concept_competitors: Replace a project’s competitorIds and regenerate the competitor-derived sections (returns a job).

Jobs (scope of the job’s type)

  • get_job: Poll a jobId for status and per-item progress.
  • get_job_results: Paginated reports for a finished batch job.
  • cancel_job: Cancel a queued or running job.

Each tool call costs one quota unit — the connection handshake and tools/list are free — and batch and Concept Compass tools reserve their extra units exactly as the REST endpoints do. list_search_fields, the five reference tools and the job tools (get_job, get_job_results, cancel_job) are free, as their REST routes are. A call refused for scope or invalid arguments costs nothing.

Output shaping: compact and fields

Full results are built for the app’s pages, not for a context window: a search page is ~40 KB of complete catalogue rows and a full get_game_report can exceed 1 MB (player history, every similar game in full). Every tool that returns data therefore takes two extra arguments that the REST endpoints do not have. Use one of them on every call — agents that read the full payloads end up saving them to disk and grepping.

ArgumentEffect
compacttrue keeps a curated projection per result type: identifiers, headline numbers and generated text — no image URL lists, no per-point histories, no raw game rows behind a report. A search page drops from ~40 KB to ~4 KB; a game report from ~1 MB to ~10 KB.
fieldsAn explicit list of dot paths to keep, e.g. ["app_id", "title", "review_count.perc_pos"]. Paths apply through arrays (similarGames.title keeps only title on each similar game). Unknown paths are ignored. When both are given, fields wins.

Shaping happens after the tool ran and never changes what was searched or generated; the meta half of the result (paging, totals) is untouched, so total is still there to reason about.

Accepted by: search_by_title, search_by_description, search_by_image, search_by_attributes, search_combined, get_game_report, search_segments, get_segment_report, list_outliers, get_concept_report and get_job_results (where it shapes each report).

What compact keeps:

  • Game rows (searches, similar games): app_id, title, short_desc, is_free, is_indie, latest_price, coming_soon, early_access, store_release_date.date, game_engine, meta_tags, developers, publishers, review_count.count, review_count.perc_pos, review_state.steam_desc, estimated_units_sold.mid, estimated_revenue.mid, estimated_wishlist.mid, scores, distance, source.
  • Game report: the compact game row, tags, segments (cluster_id, displayTitle), reviewSummary, similarGames (app_id, title, distance), generation. Dropped: playerHistory, socials, benchmarks, full similar-game rows.
  • Segments (search rows): identity, keywords, summary, total, the perc_* shares, the median_* estimates, avg_uniqueness_score, demand_score, gap_score and the warning flags. Dropped: app_ids, example_images, the long written sections.
  • Segment report: the compact segment, title, games (app_id, title, estimated_units_sold.mid, review_count.perc_pos), overview, sentiment, metrics, generation.
  • Outliers: rank, app_id, title, the two scores, the estimate midpoints, wishlist_estimate.
  • Concept report: concept, competitors (game.app_id, game.title, sales and review midpoints, distance, relevance, relevanceReason), headline, projection, resources.suggestions, publisher names, marketing (description, ideas, tags), competition, gdd.markdown, generation.

Example — the strongest segment with only what a summary needs:

{ "name": "search_segments", "arguments": { "sortBy": "demand_score", "pageSize": 5, "compact": true } }
{ "name": "get_segment_report", "arguments": { "cluster_id": "v2-3d-colony sim_city builder-cluster-61",
  "fields": ["title", "segment.demand_score", "segment.median_estimated_steam_sales", "overview.detailed_summary", "overview.market_gaps", "sentiment", "games.title"] } }

Rate limit and keys

The 60 requests/minute limit is per key and counts every request the client makes, handshake included. Read X-RateLimit-Remaining / X-RateLimit-Reset if your client exposes response headers; otherwise space calls about a second apart. Give each agent or workflow its own key (up to five per member) — they share the account’s monthly quota but each gets its own minute window.

OpenAI

  1. Open your MCP client configuration for OpenAI-compatible tooling.
  2. Add a remote MCP server entry pointing to https://game-oracle.com/api/business/v1/mcp.
  3. Configure Bearer auth with your Business API key.
  4. Save and reconnect the MCP server.
  5. Ask your agent to run a tool, for example:
    • “Use search_by_description for a cozy automation builder with async co-op and filter to paid released games.”

Claude

  1. Open Claude MCP settings (desktop or hosted client, depending on your setup).
  2. Add a remote MCP server URL: https://game-oracle.com/api/business/v1/mcp.
  3. Set Authorization: Bearer <your_key> in the server auth configuration.
  4. Confirm the server appears connected and tools are listed.
  5. Test with:
    • “Run search_segments sorted by demand_score with pageSize 10 and compact true, then call get_segment_report for the strongest opportunity with fields title, overview and sentiment.”

Perplexity

  1. Open Perplexity MCP or connectors configuration.
  2. Register a remote MCP endpoint at https://game-oracle.com/api/business/v1/mcp.
  3. Add Bearer token authentication using your Business API key.
  4. Reload connectors and verify the Game Oracle tools are available.
  5. Example prompt:
    • “Use search_by_attributes to find unreleased indie games with high uniqueness and high positive review thresholds where applicable.”

Troubleshooting

  • 401 INVALID_KEY: Missing or invalid key. Recheck the Authorization header.
  • 403 SUBSCRIPTION_REQUIRED: Your account is not currently active on the Business tier.
  • 403 INSUFFICIENT_SCOPE: The key exists but is missing required scope(s). Create a key with the right scopes in Account Settings.
  • 429 RATE_LIMITED: Too many requests in the current minute window (60 per key). Wait for Retry-After, or give this agent its own key.
  • 429 QUOTA_EXCEEDED: Monthly key quota reached. Rotate to another active key or wait for period reset.

Security Recommendations

  • Create dedicated keys per environment (dev, staging, production).
  • Scope keys to least privilege when possible.
  • Rotate keys periodically and revoke unused keys from Account Settings.