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:

.. code:: json

   {
     "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 :doc:`security`). 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.