MCP Server Setup

Game Oracle provides an MCP server, included with every Business account, so assistants and agents such as Claude, ChatGPT and Perplexity 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://www.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 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 takes as featureIds.

Games (games:read)

• get_game_report: The full report for one app_id.
• get_game_relationships: The game’s DLC, demos, packages and purchase options as listed on Steam, filterable by relation / child_type, up to 500 per page.
• 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: Create a concept from the wizard inputs and start its report (returns a job with the new conceptId). Optional featureIds (1–5, from list_features) name the concept’s core features. create_concept_project is the same tool under its old name.
• get_concept_report: The full report for a conceptId, or its generation status.
• update_concept_competitors: Replace a concept’s competitorIds and regenerate the competitor-derived sections (returns a job). Both tools still accept projectId, the field’s old name.

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.

Argument	Effect
compact	true 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.
fields	An 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, estimated_wishlist_pre_launch.mid, estimated_wishlist_post_launch.mid, time_to_complete, news.days_since_last_news, news.average_interval_days, scores, distance, source.
• Game report: the compact game row, tags, segments (cluster_id, displayTitle), reviewSummary, similarGames (app_id, title, distance, time_to_complete, the two news measures), relationships.counts, 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 (older concepts only; new concepts get their Draft GDD in the Workspace when added to a project in the app), 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://www.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://www.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://www.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.

Completion-time bands

Game searches and reports include the same completion bands and evidence as the app. time_to_complete contains time_to_complete_band, model confidence, warning codes, has_ending, the band’s source (igdb or prediction), and IGDB source/submission metadata. A missing row is null. Compact results retain this evidence, including game summaries inside reports.

Use list_search_fields to discover the supported completion filters and vocabularies.time_to_complete for ordered bands and full warning explanations. list_field_values accepts time_to_complete.time_to_complete_band, time_to_complete.confidence, and time_to_complete.warnings. Band/confidence sorts follow the vocabulary order, with missing values last.

{
	"name": "search_by_attributes",
	"arguments": {
		"attributes": {
			"time_to_complete.time_to_complete_band": ["5-10h", "10-20h"],
			"time_to_complete.confidence": "high"
		},
		"sort": { "field": "time_to_complete.time_to_complete_band", "direction": "asc" },
		"fields": ["app_id", "title", "time_to_complete"]
	}
}

The stored band prefers IGDB when available; confidence always describes the model, even for an IGDB-backed band. Raw predicted durations are not returned. See the API reference for source semantics, warnings and report field paths.

Steam news activity and store relationships

Game rows include news: days_since_last_news, average_interval_days, last_published_at and the news hub url. They measure how often the game posts to its Steam news hub, which also carries external articles, so treat them as publication activity rather than proof of patches. Missing values are null; vocabularies.news in list_search_fields explains each case.

{
	"name": "search_by_attributes",
	"arguments": {
		"attributes": { "news.days_since_last_news": { "$gte": 365 }, "coming_soon": false },
		"sort": { "field": "news.days_since_last_news", "direction": "desc" },
		"fields": ["app_id", "title", "news"]
	}
}

get_game_relationships lists DLC (app_dlc), demos (app_demo), packages (app_package) and purchase options (app_purchase_option, with Steam’s name and price text in context). get_game_report also returns them grouped as relationships, plus newsTimeline with the latest publication dates. See the API reference for every field.