Discovery Engine

Returns current plan, available credits (subscription + purchased), and
payment method status. Use this to verify you have sufficient credits
before running a private analysis.

Args:
    api_key: Disco API key (disco_...). Optional if DISCOVERY_API_KEY env var is set.

The payment method must be tokenized via Stripe's API first — card details
never touch Disco's servers. Required before purchasing credits
or subscribing to a paid plan.

To tokenize a card, call Stripe's API directly:
POST https://api.stripe.com/v1/payment_methods
with the stripe_publishable_key from your account info.

Args:
    payment_method_id: Stripe payment method ID (pm_...) from Stripe's API.
    api_key: Disco API key (disco_...). Optional if DISCOVERY_API_KEY env var is set.

This is NOT another data analyst — it's a discovery pipeline that systematically
searches for feature interactions, subgroup effects, and conditional relationships
nobody thought to look for, then validates each on hold-out data with FDR-corrected
p-values and checks novelty against academic literature.

This is a long-running operation (3-15 minutes). Returns a run_id immediately.
Use discovery_status to poll and discovery_get_results to fetch completed results.

Use this when you need to go beyond answering questions about data and start
finding things nobody thought to ask. Do NOT use this for summary statistics,
visualization, or SQL queries.

Public runs are free but results are published. Private runs cost credits.
Call discovery_estimate first to check cost.

Call discovery_upload first to upload your file, then pass the returned file_ref here.

Args:
    target_column: The column to analyze — what drives it, beyond what's obvious.
    file_ref: The file reference returned by discovery_upload.
    depth_iterations: Search depth (1=fast, higher=deeper). Default 1.
    visibility: "public" (free) or "private" (costs credits). Default "public".
    title: Optional title for the analysis.
    description: Optional description of the dataset.
    excluded_columns: Optional JSON array of column names to exclude from analysis.
    column_descriptions: Optional JSON object mapping column names to descriptions. Significantly improves pattern explanations — always provide if column names are non-obvious (e.g. {"col_7": "patient age", "feat_a": "blood pressure"}).
    author: Optional author name for the report.
    source_url: Optional source URL for the dataset.
    api_key: Disco API key (disco_...). Optional if DISCOVERY_API_KEY env var is set.

Returns credit cost, estimated duration in seconds, whether you have
sufficient credits, and whether a free public alternative exists. Always call
this before discovery_analyze for private runs.

Args:
    file_size_mb: Size of the dataset in megabytes.
    num_columns: Number of columns in the dataset.
    num_rows: Number of rows (optional, improves time estimate).
    depth_iterations: Search depth (1=fast, higher=deeper). Default 1.
    visibility: "public" (free, results published) or "private" (costs credits).
    api_key: Disco API key (disco_...). Optional if DISCOVERY_API_KEY env var is set.

Returns discovered patterns (with conditions, p-values, novelty scores,
citations), feature importance scores, a summary with key insights, column
statistics, a shareable report URL, and suggestions for what to explore next.

Only call this after discovery_status returns "completed".

Args:
    run_id: The run ID returned by discovery_analyze.
    api_key: Disco API key (disco_...). Optional if DISCOVERY_API_KEY env var is set.

Credits cost $1.00 each, sold in packs of 20 ($20/pack). Credits are used
for private analyses (public analyses are free). Requires a payment method
on file — use discovery_add_payment_method first.

Args:
    packs: Number of 20-credit packs to purchase. Default 1.
    api_key: Disco API key (disco_...). Optional if DISCOVERY_API_KEY env var is set.

Provide an email address to start the signup flow. If email verification
is required, returns {"status": "verification_required"} — the user will
receive a 6-digit code by email, then call discovery_signup_verify to
complete signup and receive the API key. The free tier (10 credits/month,
unlimited public runs) is active immediately. No authentication required.

Returns 409 if the email is already registered.

Args:
    email: Email address for the new account.
    name: Display name (optional — defaults to email local part).

Call this after discovery_signup returns {"status": "verification_required"}.
The user receives a 6-digit code by email — pass it here along with the
same email address used in discovery_signup. Returns an API key on success.

Args:
    email: Email address used in the discovery_signup call.
    code: 6-digit verification code from the email.

Returns current status and progress details:
- status: "pending" | "processing" | "completed" | "failed"
- job_status: underlying job queue status
- queue_position: position in queue when pending (1 = next up)
- current_step: active pipeline step (preprocessing, training, interpreting, reporting)
- estimated_seconds: estimated total processing time in seconds
- estimated_wait_seconds: estimated queue wait time in seconds (pending only)

Poll this after calling discovery_analyze — runs typically take 3–15 minutes.
Use discovery_get_results to fetch full results once status is "completed".

Args:
    run_id: The run ID returned by discovery_analyze.
    api_key: Disco API key (disco_...). Optional if DISCOVERY_API_KEY env var is set.

Available plans:
- "free_tier": Explorer — free, 10 credits/month
- "tier_1": Researcher — $49/month, 50 credits/month
- "tier_2": Team — $199/month, 200 credits/month

Paid plans require a payment method on file. Credits roll over on paid plans.

Args:
    plan: Plan tier ID ("free_tier", "tier_1", or "tier_2").
    api_key: Disco API key (disco_...). Optional if DISCOVERY_API_KEY env var is set.

Call this before discovery_analyze. Pass the returned result directly to
discovery_analyze as the file_ref argument.

Provide exactly one of: file_url, file_path, or file_content.

Args:
    file_url: A publicly accessible http/https URL. The server downloads it directly.
              Best option for remote datasets.
    file_path: Absolute path to a local file. Only works when running the MCP server
               locally (not the hosted version). Streams the file directly — no size limit.
    file_content: File contents, base64-encoded. For small files when a URL or path
                  isn't available. Limited by the model's context window.
    file_name: Filename with extension (e.g. "data.csv"), for format detection.
               Only used with file_content. Default: "data.csv".
    api_key: Disco API key (disco_...). Optional if DISCOVERY_API_KEY env var is set.