choson-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| CHOSON_API_KEY | Yes | Your Chosŏn API key (create one at https://quantecarlo.com/app/ under API). Required. | |
| CHOSON_API_URL | No | Base URL of the Chosŏn API. | https://quantecarlo.com/api/v1 |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Chosŏn runs conjoint studies (CBC, menu-based, MaxDiff, pricing, claims tests, volumetric). Flow: create_project -> upload_data -> check the report and design (set_design if the inferred design is wrong) -> start_fit -> quote_fit -> start_fit -> wait_for_fit -> get_result -> simulators. Before start_fit, call quote_fit with the same settings, tell the user the hardware, the estimated time and the maximum (every fit stops at 2 hours), and get their go-ahead. Report estimates with their 95% ranges; read fit warnings before drawing conclusions. For anything not covered by a tool, read api_reference and use call_api.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
| experimental | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| api_referenceA | The full Chosŏn API reference: data formats for every module, fit settings, the results JSON, every simulator and search with its fields, errors. Read it before call_api or when a format is unclear. |
| whoamiA | The account's plan and its limits (respondents, products, tasks, queued jobs) and GPU minutes this month. |
| list_projectsA | All projects on the account (id, name, kind). |
| create_projectB | Create a project. kind: cbc, mbc, maxdiff, pricing, concept or volumetric. |
| get_projectC | A project with its datasets and fits. |
| upload_dataA | Upload a responses file from the local disk (CSV in the module's long format, or a Sawtooth .CHO for CBC; see api_reference for formats). Optional design JSON for CBC. Returns the dataset: its id, the validation report (errors must be fixed before fitting; read warnings) and, for CBC, the design (check design_inferred). |
| get_datasetD | A dataset: validation report, summary, design. |
| set_designB | CBC: replace the dataset's design (attributes with name, levels, kind categorical / linear; none; price) and re-run the checks. Start from the design get_dataset returns and edit it. |
| quote_fitA | What a fit with these settings would run on, without queuing it: compute (cpu, modal_cpu, t4, h100), estimated_seconds, max_seconds (every fit is stopped at 7,200 s = 2 hours) and any notes. Same settings as start_fit. Show the user this before starting a fit. |
| start_fitA | Queue a fit. settings (all optional, see api_reference): taste (none / diagonal / full), error_shares (list of attributes), holdout (last / none), hb_baseline, constraints, covariates, classes, compute (auto / cpu / t4 / h100). Returns the fit with compute (the hardware chosen) and progress.estimated_seconds. Every fit stops at 2 hours. Call quote_fit first, show the user the hardware, the estimate and the 2-hour maximum, and get their go-ahead. |
| fit_statusB | A fit's status (queued, running, done, failed, cancelled), progress stage, error and timestamps. |
| wait_for_fitA | Poll a fit until it is done, failed or cancelled, or max_seconds pass (at most 600; call again to keep waiting). Returns the last status. |
| cancel_fitC | Cancel a queued fit at once or a running one within seconds. |
| get_resultA | The results JSON of a finished fit. Large; pass section to get one part: derived (part-worths, importances, WTP), params (mean tastes, taste spread, error shares), fit (log-likelihood, holdout hit rate, warnings), baselines (comparison models), meta (settings, design). Every estimate is {est, se, lo, hi} with a 95% range. |
| downloadA | Save a fit's file to the local disk. what: respondents.csv (per-respondent estimates), workbook.xlsx (the study workbook) or excel-simulator.xlsx (CBC, needs the Chosŏn Excel add-in). |
| simulate_sharesB | Share of preference for a shelf, with 95% ranges. products: up to 60, each {attribute: level} with levels exactly as in the design (price any number in the tested range). group: a covariate group, if the fit has them. |
| simulate_removalB | Remove one product (0-based index into products): the shares after, and where its buyers go (diversion to each remaining product and to none), with 95% ranges. The substitution question. |
| price_sweepC | Shares as one product's (0-based index) price moves across the tested range (or the given prices). |
| elasticitiesC | Own- and cross-price elasticities for a shelf, with 95% ranges. |
| forecastC | Units, revenue and profit with 95% ranges, the change against a base shelf and the chance of clearing a hurdle. request: products, occasions, prices, unit_costs, own (indexes), optional base and hurdle (see api_reference). |
| call_apiB | Any other /v1 route (see api_reference): searches (range, recommend, test-next; queued, poll with GET on the same path), optimize, segments, MBC / MaxDiff / volumetric / concept tools, survey design. path is relative to /v1, e.g. "/fits/abc123/range". JSON only; use upload_data and download for files. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
| docs | The Chosŏn API reference (v1). |
TDQS
Scored across 21 tools
Tools target clearly distinct operations: project CRUD, dataset handling, fit lifecycle (quote/start/status/wait/result/cancel), and four separate simulation queries. Minor overlap exists between forecast and simulate_shares (both take a product shelf) and call_api acts as a catch-all that can reach any route, but the descriptions delineate these well.
Most names follow a predictable verb_noun pattern (create_project, upload_data, start_fit, simulate_shares). A few deviate as bare nouns or noun_verb (fit_status, elasticities, forecast, price_sweep, whoami), with fit_status notably breaking the get_* pattern used by get_result/get_project.
21 tools is on the heavy side but justified by a genuinely complex domain spanning multiple modules (CBC, MaxDiff, pricing, concept, volumetric) with a full fit lifecycle plus simulation suite. Each tool maps to a real operation rather than redundant surface.
Covers the full workflow from project creation through data upload, fitting, results, and simulation, plus docs and an escape hatch. Gaps remain (no delete/update project, no list_fits, no dataset deletion), but call_api lets agents reach missing routes as a workaround.