misata-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| GROQ_API_KEY | No | Groq API key. | |
| GEMINI_API_KEY | No | Gemini API key. | |
| OPENAI_API_KEY | No | OpenAI API key. | |
| MISATA_PROVIDER | No | Which LLM provider to use for the three tools that read plain English. | |
| ANTHROPIC_API_KEY | No | Anthropic API key. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Misata generates realistic, referentially-intact multi-table synthetic data — no real data, no ML model, fully seeded. Use it whenever a user needs test data, a seeded database, demo data, fixtures, or a relational dataset shaped to specific outcomes (a revenue curve, a fraud rate, exact monthly aggregates). Division of labour: YOU are good at designing schemas; Misata is good at guaranteeing the math (FK integrity, exact aggregates, distributions, reproducibility). So when you know — or can design — the tables and columns the user needs, call generate_from_schema with a schema dict: that is the primary tool, and it returns a per-relationship integrity verification you can show the user. Use generate_dataset(story) only for quick one-sentence requests where Misata's own parser should design the schema (18 curated domains + structural composition for unknown ones; preview_story shows the interpretation first). To fill a real development database, use seed_database with a connection string: it reads the schema from the database itself, inserts parents before children, and verifies every foreign key against the database afterwards. It PLANS BY DEFAULT — show the user the plan, and only re-call with apply=true once they agree; never pass apply=true on a first call, and never choose truncate (which destroys data) on the user's behalf. AFTER generating, the response already carries a coherence score (0-100) and its findings: a low score means the schema is missing realism structure (correlations, profiles, time_series, state machines), so read it and revise the schema rather than the rows. audit_dataset re-runs that check on any folder of CSVs, and validate_domain flags values that are physiologically or financially impossible for a stated domain. FOR INSTANT TESTING & SQL VERIFICATION: Use create_sandbox to spin up an isolated SQLite test database pre-seeded with referentially-intact tables and get back the db_url and DDL instantly. Use query_sandbox to execute read-only verification queries against the sandbox directly.
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 |
|---|---|
| list_domainsA | List the 18 built-in business domains Misata can generate from natural language. Each domain has trigger keywords and a sample story you can pass to
|
| preview_storyA | Inspect what Misata would generate from a story — without generating any rows. Returns the detected domain, confidence, near-misses, locale, scale, and a preview of the tables that would be produced. Use this to confirm interpretation before committing to a (potentially large) generation. Args: story: Plain-English description of the dataset. rows: Default row count for the primary table (affects preview only). |
| inspect_schemaA | Return the full schema (tables, columns, relationships) for a story without generating data. Heavier than Args: story: Plain-English description of the dataset. rows: Default row count for the primary table. |
| generate_datasetA | Generate a synthetic dataset from a story and write it to disk as CSV files. Returns the output directory, file paths, row counts per table, and a small sample of rows for each table so the agent can show the user what was produced without loading every row into context. Args: story: Plain-English description of the dataset. rows: Default row count for the primary table. seed: Optional random seed (same seed → byte-identical output). output_dir: Where to write CSVs. Defaults to a fresh temp dir. sample_rows: Number of rows from each table to include in the response (max 50). |
| generate_from_schemaA | Generate a dataset from a schema you design. This is the primary Misata tool. DIVISION OF LABOUR You (the agent) design what the data should look like — the tables, columns, business rules, and declared targets. Misata handles the hard guarantees: every FK resolves, every rollup reconciles to the cent, every declared outcome curve is hit exactly, every seed produces byte-identical output. The response includes a per-relationship integrity proof. SCHEMA FORMAT {table_name: {column_name: spec, ...}, ...} TABLE-LEVEL KEYS (inside a table dict) "rows": 5000 Per-table row count; overrides the global rows arg. Always set this — one global count rarely fits all tables. "constraints" List of row-level business rules (see CONSTRAINTS below). "correlations" List of pairwise Pearson targets (see CORRELATIONS below). "state_machine" Markov terminal-state assignment (see STATE MACHINE below). COLUMN TYPES integer, float, decimal Numeric. string Short categorical or free text. text Long free text (descriptions, notes). email, phone, url, uuid Semantic strings; always valid format. date, datetime Temporal; realistic granularity applied automatically. boolean True/False with declared probability. object (json) Nested object: {"type": "object", "fields": {"email": "email", "age": {"type": "integer", "min": 18}, "tags": {"type": "list", "items": "string"}}}. Optional: "optional": [...], "optional_rate". list (array) {"type": "list", "items": , "min_items": 0, "max_items": 5, "unique_items": true, "sorted": true}. Values are JSON text. COLUMN SPEC KEYS (inside a column dict) primary_key: true Auto-incremented PK; column excluded from CSV output. foreign_key: {table, column} Child FK; referential integrity guaranteed + verified. min / max Numeric or date bounds. decimals: 2 Decimal places for float output. unique: true All values in the column are distinct. nullable: true Allow nulls (default true). enum: [...] Categorical choices. Add probabilities: [...] for weights; omit for realistic Zipf-shaped rank frequencies. probabilities: [...] Weights for enum choices; must sum to 1.0. DISTRIBUTIONS (float / integer columns) distribution: normal Also: lognormal, uniform, exponential, gamma (shape, scale), beta (a, b), poisson (lambda), binomial (n, p), power_law (alpha). mean / std Normal params. Can be a scalar OR a per-row parent-entity lookup: mean: {formula: "@patients.hba1c_baseline"} The FK is resolved per-row so each child row's distribution is anchored to its parent's value. Use this for longitudinal data where within-entity variation should be modelled separately from between-entity variation. mu / sigma Lognormal params (mu and sigma are of log(x)). min / max Hard clamps applied after sampling. Use lognormal for money, file sizes, session durations — anything right-skewed and strictly positive. Use normal for measurements. DERIVED COLUMNS formula: "quantity * unit_price" Row-level arithmetic; pandas eval syntax. formula: "hours * @employees.rate" Cross-table via FK: @parent_table.column. rollup: {from_table, fk, agg, column} Parent column that EXACTLY reconciles with child rows under JOIN. agg: sum/count/mean/ max/min. Add where: {col: val} to filter. RULE: use rollup (not formula) for any parent column that summarises child rows. Rollups are closed-form exact; formulas cannot cross the FK boundary correctly. CODE-STYLE STRINGS pattern: "SKU-\d{5}" Single pattern expanded per row. pattern: ["A/\d{5}", "\d{6}"] List: one shape drawn per row. pattern_weights: [0.7, 0.3] Weights for pattern list (optional). Supported tokens: \d (digit), [A-Z] (uppercase letter), [a-z] (lowercase), literal chars, {n} repeat count. Example: "[A-Z]{2}-\d{4}" → "AB-3721". TEXT SEMANTICS text_type: person_name Always beats column-name inference. Options: person_name, email, company, city, country, postal_code, phone, url, description, username, product_name, review_text, address, job_title. Dates: appointment times snap to 15-min business-hours grids; signups follow waking-hour rhythms; machine events keep sub-second precision. Names, genders, and emails are generated jointly and always agree. STRATIFIED DISTRIBUTIONS (profiles) Use when different subgroups need different distributions for the same column. profiles: [ {when: "arm == 'placebo'", distribution: normal, mean: -0.35, std: 0.50}, {when: "arm == 'high_dose'", distribution: normal, mean: -1.25, std: 0.55}, ] Rows that match no profile get the column's top-level distribution. The when expression is a pandas eval string; reference any already-generated column in the same table. Always list profiles after the columns they reference. INFORMATIVE MISSINGNESS (MAR) null_when: "dropout == False" Null this column when expression is true. missing_if: Missing-At-Random tied to a predictor column. predictor: hba1c_baseline relationship: higher_increases_probability # or lower_increases_probability base_rate: 0.05 # null probability at predictor median max_rate: 0.40 # null probability at predictor extreme Use null_when for status-conditional nulls (dropout_visit is null when not dropped out). Use missing_if when missingness is correlated with an observed variable. EXACT INCIDENCE CONTROL exact_incidence: Hit the declared count exactly (not approximately). mode: exact rate: 0.22 # exactly floor(n * 0.22) rows become True group_by: arm # optional: apply per group rates: {placebo: 0.15, high_dose: 0.55} # per-group exact rates Use exact_incidence instead of probability on boolean columns when the user states a precise rate that must hold in the data, not just on average. WITHIN-ENTITY TIME SERIES (longitudinal autocorrelation) time_series: Re-writes a column to have AR1 autocorrelation entity_id: patient_id within each entity group. order_by: visit_number model: AR1 # AR1 | linear_trend | random_walk | mean_reversion phi: 0.72 # autocorrelation coefficient (AR1 only) noise_std: 0.30 anchor_column: hba1c_baseline # starting value (column in the same table) trend: slope_mean: -0.08 # mean drift per step slope_std: 0.02 # per-entity slope variability Required for any longitudinal dataset (clinical visits, IoT sensors, user sessions). Without it every row is independent and the data fails any time-series test. CONSTRAINTS (table-level constraints list) {"type": "inequality", "column_a": "visit_date", "operator": ">=", "column_b": "enroll_date", "action": "cap"} Enforces column_a OP column_b. action: "cap" (snap column_a to column_b) or "drop" (remove violating rows). Works on dates and numerics. {"type": "col_range", "low_column": "min_price", "column": "price", "high_column": "max_price", "action": "cap"} Keeps low_column <= column <= high_column. {"type": "max_per_group", "group_by": "user_id", "max_count": 3} Limits rows per group value. {"type": "unique_combination", "columns": ["user_id", "product_id"]} No duplicate (col_a, col_b) pairs. Use constraints for any business rule that must hold on every row: visit_date >= enrollment_date, price > cost, resolution_day > onset_day. CORRELATIONS (table-level correlations list) [{"col_a": "bmi", "col_b": "systolic_bp", "r": 0.41}] Enforced via Iman-Conover (rank reordering): preserves each column's marginal distribution while hitting the declared Pearson r exactly. Declare correlations for any pair of measurements that co-vary in the real domain (bmi/bp, income/spending, tenure/salary). Also supports full matrix syntax: correlations: matrix: columns: [hba1c, glucose, bmi] values: hba1c: [1.00, 0.65, 0.28] glucose: [0.65, 1.00, 0.22] bmi: [0.28, 0.22, 1.00] ICC CLUSTER EFFECTS (parent table cluster_effect) cluster_effect: affects_table: visits affects_columns: hba1c: icc: 0.18 # intraclass correlation coefficient sd_total: 1.5 # total standard deviation; sd_between = sqrt(icc)*sd_total systolic_bp: sd_between: 8.0 # supply sd_between directly if preferred Applies per-parent-entity random intercepts to the named child columns. Required for multi-site or multi-centre designs — without it all sites look identical and any ICC statistical test will detect the synthetic origin. icc: 0.10-0.30 is typical for clinical measurements across sites. STATE MACHINE (table-level state_machine) state_machine: state_column: patient_status initial_state: enrolled transitions: enrolled: {on_treatment: 0.97, screen_failure: 0.03} on_treatment: {completed: 0.77, dropout: 0.23} Assigns one terminal state to every row by following the Markov chain. States with no outgoing transitions are terminal. Use for any process with defined states: clinical trial statuses, customer lifecycle, order fulfilment stages, support ticket resolution. SCHEMA-LEVEL DIRECTIVES (top-level keys, siblings of the tables) outcome_curves Declare aggregate targets the engine hits EXACTLY. [{"table": "orders", "column": "amount", "time_column": "order_date", "time_unit": "month", "value_mode": "absolute", "start_date": "2024-01-01", "avg_transaction_value": 120.0, "curve_points": [ {"month": 1, "target_value": 50000.0}, {"month": 6, "target_value": 110000.0}, {"month": 12, "target_value": 200000.0} ]}] ALWAYS use this when the user states what a number should sum to per period: "revenue grows from $50k to $200k", "Q4 spike", "10x growth". avg_transaction_value drives row count per period; set it to roughly the median row value for that column. rate_curves Per-period rate targets for boolean/categorical columns. [{"table": "transactions", "column": "is_fraud", "time_column": "transaction_date", "rate_points": [ {"period": "2024-01", "rate": 0.02}, {"period": "2024-Q4", "rate": 0.05} ]}] Use when fraud rate, churn rate, or conversion rate changes over time. group_shares Exact shares of a measure across a categorical column. [{"table": "orders", "measure": "amount", "group_column": "plan", "shares": {"Starter": 0.2, "Pro": 0.5, "Enterprise": 0.3}}] The measure sums to those proportions per group, exactly. Paired with an outcome_curves on the same table+measure, the split holds inside every declared period. Use for any "A is 40% of revenue, B is 35%..." statement. waterfalls Movements that reconcile to declared running balances. [{"table": "mrr_movements", "starting_value": 100000, "points": [{"period": "2026-01", "ending_value": 106000}, ...], "inflow_shares": {"new": 0.7, "expansion": 0.3}, "outflow_shares": {"churn": 1.0}}] Use for MRR bridges, cash-flow statements, any "opening + inflows - outflows = closing" ledger that has to tie out. stock_flows Per-unit inventory identity: closing = opening + received
no_overlap An entity is in one place at a time: its [start, end) intervals never overlap. [{"table": "visits", "key": "resident_id", "start": "arrived_at", "end": "left_at"}] capacity A resource never holds more concurrent intervals than its capacity (a constant "capacity", or "capacity_column" on its table). [{"table": "visits", "resource": "place_id", "start": "arrived_at", "end": "left_at", "capacity_column": "seats"}] A relationship's "parent_end" keeps a child inside its parent's span: {"parent": "visits.visit_id", "child": "orders.visit_id", "parent_time": "arrived_at", "parent_end": "left_at", "child_time": "ordered_at"} lifecycles A state machine with legal transitions (stricter than a table-level state_machine: illegal jumps are impossible, not just unlikely). [{"name": "order_flow", "table": "orders", "state_column": "status", "start_column": "placed_at", "initial": "placed", "states": [{"name": "placed"}, {"name": "paid"}, {"name": "shipped"}, {"name": "delivered"}, {"name": "refunded", "terminal": true}], "transitions": [["placed","paid"],["paid","shipped"], ["shipped","delivered"],["delivered","refunded"]]}] missingness Why a value is missing, conditionally (schema-level MNAR). [{"table": "contacts", "column": "notes", "rate": 0.75, "else_rate": 0.05, "when_column": "is_active", "when_op": "==", "when_value": false}] The null rate is exact per branch. Use when missingness itself carries signal a cleaning step should be tested against. processes How each case moves through steps over time, written out as an event-log table (one row per event: case key, step, activity, timestamp). Use for support tickets, claims, onboarding funnels, order fulfilment, anything where the user wants an event log, a process-mining dataset, rework loops or realistic step durations. [{"name": "ticket_flow", "cases_table": "tickets", "case_key": "ticket_id", "start_column": "opened_at", "initial": "opened", "transitions": {"opened": {"triaged": 1.0}, "triaged": {"resolved": 0.85, "escalated": 0.15}, "escalated": {"resolved": 1.0}, "resolved": {"closed": 0.9, "reopened": 0.1}, "reopened": {"triaged": 1.0}}, "dwell": {"opened": {"distribution": "lognormal", "mu": 0, "sigma": 0.8, "unit": "hours"}}, "final_state_column": "status"}] A state with no transitions row is terminal. Each row sums to 1. The event table is named "_events". Structure is exact and audited; path shares and durations are drawn from the declaration. DIRTY DATA ON PURPOSE (exact counts, so a test has a known number to find) duplicates [{"table": "contacts", "count": 60}] typos [{"table": "contacts", "column": "city", "count": 120}] outliers [{"table": "orders", "column": "amount", "count": 40}] Each injects exactly that many defects, leaving primary/unique/foreign keys intact. Use when the user is building or testing a data-quality or cleaning pipeline. preset Use-case defaults: "demo" (dates end today, clean), "test" (<=200 rows, fixed seed), "load" (x10 rows), "ml" (declared nulls/outliers/typos/duplicates, keys protected), "eval" (current dates, modest dirt). Declarations always win. domain Domain hint for post-generation validation.
"domain": "clinical_trial" # or "clinical", "financial", "fintech"
When set, generate_from_schema runs domain validation automatically and
returns it as There are ~24 schema-level declarations in total. The ones above cover the common cases; for the rest (retention cohorts, DAG edges, closure tables, graph motifs, time grids, bitemporal history) fetch https://misata.studio/docs/reference/declarations.md and check the exact key before inventing one. DESIGN RULES — follow these to get the best result in one pass
Args: schema: Dict of table defs plus optional schema-level directives. rows: Default row count for tables without rows. seed: Random seed (same seed → byte-identical output on any machine). output_dir: Where to write CSVs. Omit to use a fresh temp dir. sample_rows: Rows per table to include in the JSON response (max 50). |
| seed_databaseA | Fill a live Postgres or SQLite database with realistic, connected data, read from the database's own schema. Reads the tables, columns, and foreign keys directly from the target database, generates data that respects them, inserts parents before children, then queries the database back to confirm every foreign key resolves. No schema file and no ORM are needed: a connection string is enough. SAFETY — this is the only Misata tool that writes to a user's database:
Args:
db_url: Connection string, e.g. Returns:
A plan ( |
| create_sandboxA | Create and seed a real, isolated SQLite sandbox database for testing. Perfect for AI coding agents: spins up a queryable database with realistic, referentially intact tables (0 orphan foreign keys) so you can test SQL queries, analytics logic, or application code immediately without touching a real database. Args: domain: Pre-built domain template ('saas', 'ecommerce', 'fintech', 'healthcare'). story: Plain-English description (e.g. 'A restaurant with tables, bookings, and guests'). schema: Explicit schema dict if you want exact column control. rows: Base row count (default: 100). Transactions scale proportionally. seed: Random seed for 100% reproducible results (default: 42). db_path: Target SQLite file path (default: '.misata/sandbox.db'). Returns: Dictionary with db_url, db_path, table summaries, DDL, and sample verification queries. |
| query_sandboxA | Execute a read-only SQL query against the sandbox database. Allows AI coding agents to verify SQL queries, test aggregations, or inspect data in the sandbox directly without opening external terminals. Args: query: SQL SELECT query to execute. db_path: Optional path to the database (defaults to '.misata/sandbox.db'). limit: Max rows to return (default: 100). Returns: Dict with columns, rows (as list of dicts), row_count, and execution status. |
| validate_yamlA | Validate a Runs both checks in sequence:
Use this when an agent has authored or edited a misata.yaml on the
user's behalf and wants to confirm it parses and will actually
generate before invoking Args: yaml_text: The full contents of a misata.yaml file as a string. Returns:
|
| audit_datasetA | Score a folder of CSVs for the contradictions a human reader would catch. This is Misata's coherence audit run on data that already exists — data an agent generated in an earlier step, data a user built by hand, or the output of some other tool. It checks, among other things:
A score of 100 is clean. Below ~85 usually means the schema is missing
realism structure, not that individual rows need patching: add
Args:
dataset_dir: Directory containing one CSV per table (e.g. the
Returns:
|
| explain_schemaA | Show what generate_from_schema would do with a schema, without generating. Call it before Args: schema: The schema dict you would pass to generate_from_schema. seed: The seed you would generate with. max_invariants: How many invariants to include in the response. Returns:
|
| solve_outcomeA | Find outcome-curve values that make SQL metrics over the data hit targets. Use it when the number that matters is computed from the generated
tables rather than declared on them: net revenue after refunds, revenue
after a fee, a ratio of two tables. Each query runs in DuckDB over the
generated tables and returns two columns, the period and the value, one
row per period. Each target names a metric, the Nothing is written. On success, replace each lever curve's
Args:
schema: The schema dict, with an outcome curve per lever.
queries: Metric name to DuckDB query, e.g. Returns:
|
| attest_datasetA | Prove a written dataset holds what its schema declared, in a standard format. Recomputes every invariant the schema implies (outcome-curve totals, rate
anchors, group shares, ledger identities, foreign keys, unique columns)
with DuckDB against the files, and pins each file by SHA-256. Writes
Use it after Args:
dataset_dir: Folder with one Returns:
|
| check_realismA | Find the statistical shapes that make a dataset look generated. Where Fix a finding in the schema, not the rows: lognormal for money, a curve or
weights for time, Args:
dataset_dir: Directory with one CSV per table (the Returns:
|
| validate_domainA | Flag values that are physiologically or financially impossible for a domain. Where Use after generating a dataset in a regulated or measurement-heavy domain, or when the user asks "is this data plausible for a real clinic / bank?". Args:
dataset_dir: Directory containing one CSV per table.
domain: One of Returns:
|
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 15 tools
Most tools are clearly separated and the descriptions even cross-reference each other (audit_dataset vs check_realism vs validate_domain, preview_story vs inspect_schema, generate_dataset vs generate_from_schema). The remaining soft spots are preview_story/inspect_schema/explain_schema, which all 'show you what you'd get' for slightly different inputs, and create_sandbox vs seed_database, which both write to a database but differ in source of truth.
Every name is snake_case with a verb-first pattern (validate_yaml, audit_dataset, attest_dataset, check_realism, seed_database). Minor deviation: generate_from_schema is verb_preposition_noun while its sibling is generate_dataset, a near-pair that differs only by a preposition.
15 tools sits at the top of the well-scoped band and each one owns a distinct stage: authoring, previewing, validating, generating, attesting, DB seeding, sandbox CRUD, and outcome solving. Nothing looks like filler or a redundant wrapper.
The lifecycle is fully covered end to end: domain discovery and story preview, schema dry-run and YAML validation, two generation paths, outcome solving, three complementary quality checks, cryptographic attestation, plus live DB seeding and a queryable sandbox. The only gaps are trivial (no sandbox delete/cleanup, no patch-in-place of an existing dataset), both workaroundable outside the tool surface.