The MCP server#

The refinery ships an MCP server — a Model Context Protocol endpoint that lets AI assistants and other MCP clients work directly against a refinery instance. Through it an assistant can explore the catalog, sample and analyse data, read and author formulas, and manage dashboards, figures and balances — all under the same authentication and role model as the rest of the refinery.

Note

This is a pro-only feature of the Timeseries Refinery. If interested, please visit: https://timeseries.pythonian.fr/#ouroffer.

What it exposes#

Its capabilities fall into a few families:

  • discovery — search the catalog, read metadata, follow dependencies;

  • data — sample recent values, compute statistics, detect regimes and anomalies;

  • formulas — read, expand, test and (with write access) author computed series and groups;

  • dashboards, figures and balances — browse and manage the visualization objects;

  • baskets — reusable saved queries

  • notes - a per-user knowledge base;

  • tasks — inspect the scheduler and recent runs;

  • guides — built-in, self-documenting help (see Built-in guidance).

Connecting a client#

Any MCP client that speaks streamable HTTP can connect to the server’s /mcp endpoint. There is nothing to install on the client side — point your client at the endpoint URL as a remote HTTP MCP server.

Clients are configured either through a command that registers a remote HTTP server, or through a JSON configuration such as:

{
  "mcpServers": {
    "refinery": {
      "type": "http",
      "url": "https://your-refinery-host/mcp"
    }
  }
}

On first use the client performs an OAuth2 login in your browser against the refinery’s identity provider; subsequent requests carry the resulting token.

Authentication and roles#

Access uses the same OAuth2/OpenID Connect authentication as the rest of the pro application, and the same four-tier role ladder — guest < ro < rw < admin (see Securing the Refinery). Your role governs what the assistant may do on your behalf:

  • read tools require the ro, rw or admin role;

  • write tools — anything that creates, modifies or deletes an object — require rw or admin;

  • guest can call nothing.

In the tool catalog below, write tools are marked (write); all others are read-only.

Built-in guidance#

The server is designed to onboard an assistant on its own. The get_*_guide and get_*_spec tools listed below return structured instructions and language references, so a client can learn the query language, the formula operators, or the figure/dashboard/balance syntaxes on demand rather than from external documentation.

A single MCP prompt, welcome, acts as the entry point: it presents a menu of activities — discover the instance, analyse the gold layer, detect anomalies, create and test formulas, explore and manage dashboards — and routes the assistant to the relevant guide. It also reminds the assistant to check the notes at the start of a session, and to ask for explicit confirmation before creating or changing anything.

Available tools#

Notes — a knowledge base the server keeps for the instance.

  • list_notes — list all note keys.

  • get_note — read one note.

  • save_note (write) — create or update a note (full replace, append, or find-and-replace).

  • delete_note (write) — remove a note.

Note

The notes are a collaborative, instance-wide knowledge base: everyone using the instance shares the same notes. An assistant can record what it learns about the refinery — naming conventions, a domain map, recurring gotchas — and that knowledge persists across sessions and is available to every other user.

Discovery, search

  • find_items — search series or groups with the lisp query language.

  • get_info — global statistics about the instance.

  • list_metadata_keys — all metadata keys in use.

  • get_dependents — what depends on an item (impact analysis).

  • troubleshoot_item — metadata, internal metadata and, for formulas, depth and dependencies.

Series

  • get_fresh_data_sample — a recent data window with statistics (auto-downsampled to a readable size).

  • analyze_series — change-point segmentation into regimes (flat, ascending, oscillating, …).

  • get_activity_summary — per-series statistics across a basket, ranked by variability.

  • rename_series (write) — rename a series or formula, propagating into referencing formulas.

  • delete_series (write) — delete a series or formula (irreversible).

  • update_metadata (write) — merge metadata onto a series or group.

Formulas

  • get_formula — a formula definition, optionally expanded.

  • eval_formula — evaluate an ad-hoc formula without saving it.

  • get_gold_layer_formulas — the deepest, highest-value formulas (expensive).

  • register_formula (write) — create or replace a series or group formula.

Baskets

  • list_baskets — saved queries and their definitions.

  • resolve_basket — evaluate a basket to its matching items.

  • register_basket (write) — create or update a basket.

  • delete_basket (write) — remove a basket.

Figures

  • list_figures — the figure catalog (paginated, by variant).

  • figure_dependents — dashboards referencing a figure.

  • get_figure — a figure’s canonical definition.

  • update_figure (write) — create or replace a figure (validated before saving).

  • rename_figure (write) — rename, rewriting referring dashboards.

  • delete_figure (write) — delete a figure (refuses if referenced, unless forced).

Dashboards

  • list_dashboards — dashboards with title and description.

  • get_dashboard — a dashboard’s canonical definition.

  • update_dashboard (write) — create or replace a dashboard.

  • rename_dashboard (write) — rename a dashboard.

  • delete_dashboard (write) — delete a dashboard.

Balances

  • list_balances — balance definitions in the registry.

  • get_balance — a balance’s canonical definition.

  • update_balance (write) — create or replace a balance (validated).

  • rename_balance (write) — rename, rewriting referencing figures.

  • delete_balance (write) — delete a balance (refuses if referenced).

Tasks and schedules

  • list_operations — registered scheduler operations.

  • list_schedules — scheduled rules and their decoded inputs.

  • list_tasks — recent task runs with their status.

Guides and help

  • get_query_syntax — the search query language.

  • get_operators — the formula operators (introspected from the registry).

  • get_discovery_guide — a methodology to map an unfamiliar refinery.

  • get_formula_building_guide — a step-by-step formula authoring workflow.

  • get_gold_layer_analysis_guide — how to find and read the highest-value formulas.

  • get_anomaly_detection_guide — a workflow for spotting outliers and gaps.

  • get_figure_spec — the figure definition language.

  • get_dashboard_spec — the dashboard definition language.

  • get_balance_spec — the balance definition language.