# EU Trade Explorer -- MCP bridge


> Bridge to the tradedashboard.eu EU Trade Explorer API (Eurostat Comext customs-trade + PRODCOM industrial-production statistics).

## Typical Workflow

1. **Resolve the product**: If you don't already know the right Combined Nomenclature (CN) product code, call `resolve_product_code` with a keyword (e.g. "glass jars") or a candidate code. Note that CN nomenclature is often coarser than a colloquial product name. For example, there is no code for "glass jars" alone, only a heading (7010) that bundles jars with bottles and closures; check `has_subcodes` and the returned hierarchy before assuming a code is a clean match.

2. **Choose your path**:
   - **Short path**: Call `get_full_report` for a rundown of the most important stats. If you want something quick and simple, you can already stop there, analyse that data, and write your report.
   - **Long path**: There are close to 28 functions you can call iteratively depending on your angle. Start with `get_overview` for headline totals, then drill into `get_partner_detail`, `get_reporter_detail`, `get_concentration`, `get_specialisation`, `get_net_import_reliance`, etc. as needed.

## Query Arguments

All MCP tools accept the same `query` object with these parameters:
- `product`: Combined Nomenclature code(s)
- `reporter`: Declaring entity (EU member state, etc.)
- `partner_set`: Named partner preset or custom list
- `period_start`, `period_end`: Analysis window (YYYY-MM format)
- `frequency`: 'month', 'quarter', or 'year'
- Plus tool-specific options

Every tool accepts `compact=true` to condense long numeric time series into summary statistics (first/last/min/max/mean/pct_change) instead of full series. Use this when you just want main trends; omit it when identifying shocks and outliers.

## Dashboard Navigation

You typically do not need to plot data yourself. Instead, refer to the relevant menu item/tab on the website. Note: there is no `get_url`-style tool because dashboard views don't map 1:1 onto bridge tools. A single dashboard tab often combines several tool calls (e.g., the "concentration" tab shows `get_concentration` for both `entity_level='partner'` and `'reporter'` side by side), so links belong to views (`menu`+`tab`), not individual tool responses.

### Dashboard Structure

| Menu | Name | Tab | Description |
|------|------|-----|-------------|
| `overview` | Overview | `overview` | Synthesis |
| | | `partners` | Breakdown by trading partner |
| | | `reporters` | Breakdown by EU member state |
| | | `map-imports` | Geographic view of imports |
| | | `map-exports` | Geographic view of exports |
| `concentration` | Market structure | `concentration` | Evolution of trade concentration |
| | | `concentration-map` | Geographic view of trade concentration |
| | | `specialisation` | Intra-European comparative advantage |
| | | `production-volumes` | Production volumes |
| `cross-section` | Cross-section | `compare` | Quantities by product |
| | *(for multi-code or drilling)* | `product-volatility` | Volatility by product |
| | | `product-concentration` | Concentration by product |
| `volatility` | Volatility & shocks | `volatility` | Volatility |
| | | `supply-shocks` | Sudden volume changes |
| | | `price-shocks` | Rapid price changes |
| | | `pattern-shifts` | Price & volume change summary |
| `vulnerability` | Strategic autonomy | `net-import-reliance` | Net import reliance |
| | | `trade-intensity` | Trade intensity |
| | | `export-propensity` | Export propensity |
| | | `subcontracting-intensity` | Evolution of sub-contracting intensity |
| | | `subcontracting-members` | Geographical distribution of sub-contracting intensity |

## Methodological Notes

These notes are reproduced here so figures can be interpreted and cited correctly:

- **`concentration/concentration`**: The Herfindahl-Hirschman Index (HHI) measures how concentrated trade is across partners or EU Member States. For each period, it sums the squared market shares of each entity, producing a score from 0 (perfectly spread across many partners) to 10,000 (one partner holds 100% of the market).

- **`concentration/specialisation`**: Intra-EU revealed symmetric comparative advantage (RSCA) per member state: whether a member state's share of intra-EU exports for a specific product is larger than its share of intra-EU exports overall. The Balassa index (RCA) compares a member state's export share of the product against its export share of all products (both measured within the EU); RSCA rescales RCA symmetrically onto [-1, 1]: RCA = (x_p / x_total) / (X_p / X_total), RSCA = (RCA - 1) / (RCA + 1), where x is the member state's intra-EU exports and X is the EU total (p = this product, total = all products). -1 is under-specialised, 0 is the EU average, +1 is strongly specialised. Intra-EU flows are distorted by the Rotterdam/Antwerp effect, so read the index with caution.

- **`volatility/volatility`**: Each cell is the coefficient of variation (CV): standard deviation divided by the mean, for a single partner × product pair over the selected period. Inactive periods (zero quantity) are excluded so they don't distort the result. A higher CV means the flow swings more relative to its typical level. Only the most active partners by volume are selected for this tab.

- **`volatility/supply-shocks`**: Detects abnormal collapses in trade volumes. For each partner/product pair with enough sustained activity, the algorithm flags periods where volume drops well below that pair's historical average. To surface more (weaker) shocks: lower the minimum-deviation threshold, raise the cumulative trade share considered, extend tolerated gaps, lower the minimum number of stable years required, or treat any small drop (even ~5%) as a shock.

- **`volatility/price-shocks`**: Detects sudden price variations while accounting for each flow's usual volatility. The algorithm compares each period's price against a retrospective reference window, then flags regime changes whose amplitude exceeds a configurable multiple of the coefficient of variation.

- **`volatility/pattern-shifts`**: Suggested workflow: note the usual volatility of the entities that interest you (via `volatility/volatility`), check for significant volume/price variations there, use `supply-shocks`/`price-shocks` to identify the dates where these are most pronounced, then use one of those dates as `query.midpoint`.

- **`vulnerability/net-import-reliance`**: NIR expresses net imports (imports minus exports) as a share of domestic consumption in the Union: NIR = (Imports - Exports) / Apparent consumption, where Apparent consumption = Production + Imports - Exports. E.g., 40% means 40% of EU consumption of the product is met by imports; negative means the EU is a net exporter (not import-dependent). Used by the European Commission to determine whether a sector should get particular monitoring or support.

- **`vulnerability/trade-intensity`**: TI measures how open EU27 production is to international trade, following the European Commission's CEEAG methodology (used for State-aid eligibility of sectors at risk of carbon leakage): TI = (Imports + Exports) / (Imports + Production). Close to 1 = highly trade-exposed; near 0 = predominantly domestic.

- **`vulnerability/export-propensity`**: The share of EU27 production sold abroad: Export propensity = Exports / Production. E.g., 60% means 60% of the value produced in the Union is exported; re-exports or stock drawdown can push values above 100%.

- **`vulnerability/subcontracting-intensity`**: The share of EU production manufactured for someone other than the factory's owner: Intensity = Sub-contracted production / Total sold production. Near 100% signals a processing hub with little own R&D; near 0% marks an autonomous industrial base. The own/sub split only exists from 2021 onward in the PRODCOM database.

- **PRODCOM-backed tabs**: For `concentration/production-volumes` and every `vulnerability/*` tab—when a customs code maps to several PRODCOM codes, figures are aggregated across them, or, if Eurostat suppresses detail at that level, sourced from the nearest available higher aggregate. Use `query.prodcom_code` to pin one specific mapping instead of relying on that default.

- **Rotterdam/Antwerp caveat**: Whenever Belgium or the Netherlands appear as the main trading importer or exporter of a product, beware: it might just be that the bulk of the trade for that product is transiting through Antwerp or Rotterdam.

URL examples:

```
https://tradedashboard.eu/?product=870380&partner_set=non-EU+countries&period_start=2015-01&period_end=2026-04&frequency=quarter&remove_outliers=true&palette=default&menu=overview&tab=overview

https://tradedashboard.eu/?product=2822|282520&reporter=Custom+group&reporter_members=Bulgaria|Cyprus|Belgium&partner_set=North+America&period_start=2015-01&period_end=2026-04&frequency=quarter&remove_outliers=true&palette=default&lang=nl&menu=overview&tab=overview
```


## Connecting

- Transport: Streamable HTTP, at https://mcp.tradedashboard.eu/mcp
- Every request needs a bearer access token (OAuth 2.1) with auto-discovery implemented.
- A normal MCP client will follow that discovery chain and the login/consent flow automatically the first time you add this URL.
- The response is a single JSON-RPC object, `{'jsonrpc': '2.0', 'id': 1, 'result': {...}}`; the tool's own return value is under `result.structuredContent` (and as text under `result.content[0].text`). Any tool can be called this way -- `params.arguments` is just that tool's keyword arguments (`query`, `compact`, ...) as a JSON object.

## Tools (35 total)

- **guidelines_to_write_a_report** -- Read this first. Returns the guidelines for how to use this bridge's tools to research and write a trade report -- the recommended workflow (resolve a product code, then either `get_full_report` for a quick rundown or the individual tools for a deeper dive), the shared `query` object, and the `compact` option. Call this before guessing at tool use.
- **get_countries** -- Reference data for reporters/partners: selectable EU/Euro-area/member states, named partner presets, predefined reporter/partner groups, and per-language country-name translations. Use this to find valid values for the `reporter`, `partner_set`, `partners` and `reporter_members` fields used throughout the other tools' `query` argument.
- **get_chapters** -- List all top-level Combined Nomenclature chapters (2-digit codes). Bootstraps browsing the nomenclature top-down; drill into a chapter with `get_subtree`.
- **get_subtree** -- Return the Combined Nomenclature sub-tree rooted at `code` (its children, and their children, ...), each with a `code` and a `text` description. Use this to see whether a heading you're about to use (e.g. as `query.product` elsewhere) is actually a clean match, or bundles several distinct sub-products together.
- **validate_code** -- Validate and describe one or more Combined Nomenclature codes. For a single code, returns the full hierarchy of description levels (`levels`), the resolved `product_name`, and `has_subcodes`. For a comma-separated list, returns `{"results": [...]}` with one entry per code (each either a success dict or an `{"code", "error"}` pair).
- **search_codes** -- Keyword/code search over the Combined Nomenclature (or PRODCOM). Returns ranked `{code, label, path}` candidates. Prefer `resolve_product_code` for a one-call keyword-or-code helper; use this directly if you specifically want the raw ranked candidate list.
- **get_data_range** -- Return the period coverage (`data_min`/`data_max`, 'YYYY-MM') actually cached for the given product code(s) -- use before picking `period_start`/`period_end` so you don't request an empty window.
- **get_overview** -- Headline figures: total import/export quantities, values and weighted-average prices per period, the trade balance, and a top-partner breakdown. The best first call for any new product/reporter slice.
- **get_partner_detail** -- Per-partner import/export breakdown. For each flow, the top-N trading partners ranked both by quantity and by value (so you can compare volume-based vs. value-based rankings), each with its own quantity, value and price time series, plus an optional 'Other' bucket.
- **get_reporter_detail** -- Per-EU-member-state import/export breakdown -- the reporter-side counterpart of `get_partner_detail`. Top-N member states (by quantity and by value) with their quantity, value and price series. Aggregate reporters (EU, Euro area, groups) are excluded from the ranking.
- **get_map_data** -- Choropleth-ready aggregates: per-period totals (quantity, value, price) for imports and exports, keyed by GISCO country code on both the reporter and partner sides.
- **get_top_entities** -- Just the ordered list of top entities for a slice -- no time series. A lightweight helper for populating entity pickers or quickly checking who the top partners/reporters are without pulling full series.
- **get_production_series** -- EU27 and per-country PRODCOM production series: EU quantity, EU production unit value, and the same two per reporting country (all DS-059358 reporters, not just EU-27, since production data carries no trade columns). Country-level figures are heavily confidentiality -suppressed; suppressed/absent values come back as null, not zero. Use `query.prodcom_code` to pin a specific PRODCOM mapping when a CN code maps to several.
- **get_product_compare** -- Sub-product comparison: for a single parent CN code, expands into its children (or, for a multi-code request, compares the entered codes directly) and returns per-subcode quantity/value/price series for both flows -- so each sub-product plots as its own line instead of being aggregated away. A leaf code with no children returns `leaf: true`.
- **get_concentration** -- Herfindahl-Hirschman Index (HHI) of trade concentration across partners or member states, per period (0 = perfectly spread, 10000 = one entity holds the whole market), plus the top-8-by-value share breakdown (rest bundled as 'Others'). Higher HHI = more dependent on a handful of counterparties.
- **get_concentration_compare** -- Partner-concentration (HHI) compared across sub-products: one HHI line per sub-product rather than per flow, to see which sub-products drive a parent code's overall concentration.
- **get_concentration_map** -- Cross-sectional HHI per country for one year -- the choropleth counterpart of get_concentration. 'partner' entity_level = for every EU member state, HHI of its trade across partners; 'reporter' = for every partner, HHI of its trade across EU member states (subject to the Rotterdam/Antwerp entry-point distortion).
- **get_specialisation** -- Intra-EU revealed symmetric comparative advantage (RSCA) per member state -- a Balassa index benchmarked against the EU instead of the world. Runs -1 (under-specialised) to +1 (strongly specialised), value -based and intra-EU only. Treat with caution: intra-EU flows are distorted by the Rotterdam/Antwerp quasi-transit effect.
- **get_production_concentration** -- How concentrated production of a product is across all DS-059358 reporting countries (PRODCOM; EU member states plus EFTA/candidate/other reporters -- not only the EU-27). HHI of PRODVAL across countries over time, plus each country's production share. Suppressed/absent country figures come back as null, not zero. Use `query.prodcom_code` to pin a specific PRODCOM mapping.
- **get_volatility** -- Coefficient-of-variation (CV = stdev / mean) volatility per partner/reporter x product pair, over inactive-period-excluded history. Higher CV = the flow swings more relative to its typical level. Returns per-entity CV bars (with drill-down series) and, unless include_heatmap=false, an entity x sub-product CV heatmap.
- **get_pattern_shift** -- Before/after trade-pattern shift around a split point (`query.midpoint`): for each entity, compares average quantity and price before vs. after, and returns scatter points (quantity-change % vs. price-change %) with quadrant labels -- top-right = demand-driven growth, top-left = supply constraint/monopoly risk, bottom-right = dumping/oversupply risk, bottom-left = market contraction. Suggested workflow: spot a shock date via get_supply_shocks / get_price_shocks first, then set it as `query.midpoint` here.
- **get_supply_shocks** -- Detect abnormal collapses in trade volumes ("sudden volume changes"). Flags periods where a partner/product pair's volume drops well below its historical average (>2 sigma by default). Returns ranked shock events per flow, each with timeline phases (baseline, decline, disruption, recovery, ...), magnitude, abnormality score and underlying series.
- **get_price_shocks** -- Detect sudden price regime shifts ("rapid price changes"), accounting for each flow's usual volatility so naturally volatile flows aren't over-flagged. Returns ranked shock events per flow with timeline phases (price spike/drop, volatile trade, return to baseline, ...), magnitude and series.
- **get_net_import_reliance** -- Net Import Reliance (NIR) = (Imports - Exports) / Apparent consumption, annual, joining PRODCOM production with Comext trade. E.g. 40% means 40% of EU consumption is met by imports; negative means the EU is a net exporter. Returns the NIR % series, its supply/disposition components, sibling-category/per-code comparisons, the resolved PRODCOM codes and availability notes (CN-to-PRODCOM mapping is not always 1:1; see the `self.notes` / `unavailability_type` fields in the response). Use `query.prodcom_code` to pin a specific mapping.
- **get_trade_intensity** -- Trade Intensity (TI) = (Imports + Exports) / (Imports + Production), annual. Near 1 = highly trade-exposed sector; near 0 = predominantly domestic. Used in the Commission's CEEAG methodology for carbon-leakage / State-aid eligibility. Returns the TI series, its components, sibling-category/per-code comparisons, resolved PRODCOM codes and availability notes.
- **get_export_propensity** -- Export Propensity = Exports / Production, annual: the share of EU production that is exported. Not clamped -- values above 100% are legitimate (re-exports, stock drawdown, scope differences). Returns the export-propensity matrix, a sibling/per-code comparison, resolved PRODCOM codes and availability notes.
- **get_subcontracting** -- EU27 sub-contracting intensity: the share of sold production that is toll (sub-contracted) manufacturing rather than own-account output. Returns intensity (%) across value/quantity, its component series, per-period data-quality status, resolved PRODCOM codes and availability notes. The own/sub split only exists from 2021 onward.
- **get_subcontracting_members** -- Per-country sub-contracting intensity (PRODCOM): for each reporting country, the share of its sold production that is toll manufacturing -- which countries act as processing hubs vs. autonomous producers. Spans all DS-059358 reporters that report the own/sub split; others simply don't appear. Country cells are heavily confidentiality-suppressed (null, not zero, when absent).
- **resolve_product_code** -- Resolve a free-text query or CN code(s) into validated product code(s) with descriptions -- the recommended first step before using a code as `product` in any other tool's `query`. Saves the search -> validate -> (optional) subtree round-trip: a bare keyword runs a search, a single code (or comma-separated list) is validated and described directly. Tip: Comext/CN nomenclature is frequently coarser than a colloquial product name (e.g. there is no code for "glass jars" alone -- only heading 7010, which bundles jars with bottles, flasks and closures). Check `has_subcodes` and, if useful, set `include_children=true` to see whether a finer sub-code is actually a better match before committing to one code for a whole report.
- **get_product_profile** -- Report-section helper ("Scope & definitions"): the resolved product code + label, a one-sentence caveat when the code bundles several sub-products (`has_subcodes`), the data-coverage window actually cached for it, and whether it has a usable PRODCOM mapping (gating the autonomy/vulnerability section). Deliberately thin -- no full CN hierarchy breadcrumb or sibling enumeration. Returns `{narrative_facts, chart_data, available, reason}` -- see `get_market_summary` for the shape this convention follows across all of this bridge's report-section helpers.
- **get_market_summary** -- Report-section helper ("General overview"): condensed, report-ready digest of how a market has evolved over the chosen window -- one call instead of separately fetching and cross-referencing get_overview + get_reporter_detail + get_concentration + get_net_import_reliance yourself. Set `query.frequency = "year"` for a multi-year evolution summary (recommended over the model's default of "quarter"). Every figure reflects `query` exactly as given -- the same product/reporter/partner_set/period slice a dashboard user would have selected. Nothing here substitutes a different reporter or partner_set (e.g. to contrast intra-EU against extra-EU trade): call this again with a different `query.partner_set` for that, the same way a dashboard user would switch the sidebar's selector. Returns `{narrative_facts, chart_data, available, reason}`. `narrative_facts` combines, for the flow selected by `query.partner_set`: - Headline trade: first/last/min/max/pct_change for export & import value, quantity and price, plus the trade-balance trend. - Partner concentration: first/last/pct_change of the value-based HHI for imports and exports. - Top partners *and* top EU reporters by value: each one's first/last/pct_change -- i.e. who is gaining or losing share. - Net import reliance: first/last/pct_change of the annual NIR % for `query`'s own `reporter`/`partner_set` (only `frequency` is normalised to "year", since NIR is structurally annual and the upstream API always returns it that way regardless); omitted if the product has no PRODCOM mapping. `chart_data` carries the full-fidelity headline trade and top-partner/ top-reporter series for charting.
- **get_market_structure_summary** -- Report-section helper ("Market structure"): combines, in priority order, the intra-EU specialisation snapshot (`get_specialisation`, already map-ready), partner-concentration detail (`get_concentration`, keeping the top-8-by-value share breakdown as `chart_data` alongside the condensed HHI trend) and, when a PRODCOM mapping exists for the product, EU production volumes (`get_production_series`). These three are independent data sources bundled only because they all describe "market structure" -- the specialisation RSCA is trade-based and has no relation to the PRODCOM production figures; treat them as separate findings, not a single connected story. `most_specialised_reporters` / `least_specialised_reporters` are pre-sorted by actual RSCA (highest/ lowest first respectively) -- use them as-is rather than re-deriving a ranking. `query.prodcom_code` is passed through untouched -- picking among ambiguous PRODCOM mappings is left to the caller, never guessed here. Returns `{narrative_facts, chart_data, available, reason}`.
- **get_volatility_summary** -- Report-section helper ("Volatility & shocks"): the entities analysed are picked by `get_volatility` (ranks by trade volume, reports each one's CV) and by `get_price_shocks`/`get_supply_shocks` at default parameters (both already scoped to top-value partners via `cumulative_share=0.8`) -- never re-picked from the shocks themselves. Retries shock detection once with loosened thresholds before concluding "no shocks"; an empty result is itself a reportable finding, not a gap. When shocks are found, the top flagged entities and a derived `midpoint` feed `get_pattern_shift` as the section's priority chart; when none are found (even after the retry), the volatility bar chart is the fallback priority chart and stability is the finding. Returns `{narrative_facts, chart_data, available, reason}`.
- **get_autonomy_summary** -- Report-section helper ("Autonomy & vulnerability"): net import reliance (`get_net_import_reliance`) is always the headline fact/chart. Trade intensity and export propensity (`get_trade_intensity` / `get_export_propensity`) are both computed, then a deterministic salience score -- distance from an unremarkable ~50% band, plus the magnitude of its own change -- decides which one leads the narrative; this choice is never left to the caller. `trade_intensity_pct` is returned fully unit-consistent (first/last/min/max all expressed as a percentage, matching `export_propensity_pct`). Sub-contracting is deliberately not included in this section at all -- it is an unrelated, tiny-base PRODCOM series that only muddied the narrative. Returns `{narrative_facts, chart_data, available, reason}`.
- **get_full_report** -- Fetch every report section (scope, overview, market structure, volatility, autonomy) for one shared `query` in a single call, instead of calling `get_product_profile` / `get_market_summary` / `get_market_structure_summary` / `get_volatility_summary` / `get_autonomy_summary` separately yourself. Guarantees all five sections describe the exact same product/reporter/partner/period slice -- five separate calls have no such guarantee, since nothing stops `query` from being re-typed slightly differently across them, or one of the five simply being forgotten. `query`'s own field defaults (`reporter='European Union'`, `partner_set='non-EU countries'`, `period_start='2015-01'`, `frequency='quarter'`, `remove_outliers=true`, ...) are exactly the sensible defaults for a first-cut report; override any of them for a different slice -- e.g. a specific member state, a custom partner group, a narrower period. Returns `{"query": {...}, "sections": {<name>: {narrative_facts, chart_data, links, available, reason}, ...}}` for `<name>` in `product_profile`, `market_summary`, `market_structure`, `volatility`, `autonomy`. `links` maps each `narrative_facts` key to a ready-made `https://tradedashboard.eu/...` URL for that same fact -- never construct one of these yourself; use the one already provided.

## Docs

- [Dashboard & REST API llms.txt](https://tradedashboard.eu/llms.txt) -- a different surface, see the note above
- [FAQ](https://tradedashboard.eu/faq-en.html)