MCP tools

The MCP server at https://mcp.open-climate.ai/mcp exposes 15 tools: 12 for the model and 3 that only the in-chat widgets call. One, search_emission_factors, answers a question about one item. The rest take a file of purchase or activity lines, match each line to an emission factor and return the totals. To connect, see Connect over MCP.

A platform that mounts the server behind its own reaches a narrower set, without search_emission_factors: see Integrate our MCP.

How the tools chain#

For one to five items, call search_emission_factors once per item. For more items, a ledger or a file, use the chain:

Every later tool takes the upload_id or job_id verbatim. Never pass a file path or URL in their place. No tool returns where a file is stored: an upload is named by its upload_id and its filename, a result by its job_id and its download URL.

The shared envelope#

prepare_upload, plan_emission_factor_mapping, create_lexicon and get_emission_factor_mapping_result return these five fields beside their own.

Each tool also returns a prose content[0].text that says what to do next, so a client can act on the text alone.

get_emission_factor_mcp_server_info#

Reports which build of the server you reached and which tools it registered. Read-only, no side effects. Use it to check a new connection.

Inputs. None.

Output.

search_emission_factors#

Finds emission factors for one item, such as "a factor for a laptop", "hotel night in Spain" or "steel rebar per tonne". It reads the same ranking and licence rules as the factor explorer. Read-only, no side effects.

Call it once per item, for up to five items. For more, or for a ledger or a file, use the chain: it maps every line in one job.

Inputs.

Note. Settle the quantity first and pass it as unit_family. A laptop has factors per piece (count), per kg (mass) and per euro spent (monetary), and they are not interchangeable.

Output.

Each entry in results:

prepare_upload#

Mints a short-lived upload URL for a .csv, .xls or .xlsx file. Use it when the model cannot see every row, or when there are more than 50. In a host that renders MCP Apps widgets, a drag-and-drop widget appears. Other clients get a curl one-liner in the text.

Inputs. None. The widget reads the file name when the user picks the file.

Output. The envelope, plus:

Wait until the upload has finished before you call plan_emission_factor_mapping.

upload_inline_rows#

Stores rows the model can already see as a CSV and registers them like a file. Use it for 50 rows or fewer, whether the user pasted them or attached a small file.

Inputs.

Output.

plan_emission_factor_mapping#

Profiles an uploaded file and proposes how to read it: sheet, header row, trailing rows to drop, useful columns. One short model call also infers the file's currency, the buyer's country and a two-to-three sentence description. Read-only.

Inputs.

Output. The envelope, plus:

Watch out. The profiler assumes one header row and one table per sheet. Check suggested against the preview rows. A total row whose amount a block of the file's own rows adds up to is skipped as aggregate_row. A total the job cannot check, because it has no label or sits on a separate summary sheet, double counts: drop it.

On some deployments suggested.file_context is null and requires_followup is set. The client then infers the currency, country and description itself and passes them to the mapping tool.

create_lexicon#

Decodes a file's opaque vocabulary once, such as brand names, internal abbreviations and dense technical terms, so each row is matched with those terms already explained. Optional. Call it when the descriptions are full of codes; skip it for plain language.

Inputs.

Output. The envelope, plus:

On most deployments this tool returns requires_followup instead: the client reads the file with read_procurement_input_file, builds the lexicon, and forwards domain and lexicon in file_context.

read_procurement_input_file#

Returns the uploaded rows as objects with the original columns, so the client can scan every row. Read-only.

Inputs.

Output.

map_procurement_items_to_emission_factors#

Matches every row of the upload to an emission factor. Asynchronous: it returns a job_id at once, and the result is not ready yet. Do not start a second job for the same file while one runs.

Inputs.

file_context fields, all optional:

Output.

check_emission_factor_mapping_progress#

Reports how far a job has got. Read-only. Wait at least retry_after_seconds between calls.

Inputs. job_id (string, required).

Output.

Note. During auditing, percent is 100 while the file-level check still runs. That is not a stuck job. In any other stage, a large seconds_since_last_progress is.

get_emission_factor_mapping_result#

Returns the download link and a summary report for a succeeded job. It errors on any other status. In a host that renders widgets, an emissions dashboard appears from the same data.

Inputs. job_id (string, required).

Output.

It also returns the envelope.

report_stats carries total_rows, matched_rows, unmatched_rows, match_rate_pct, by_library (rows per library), emissions_by_library (kg CO2e per library), total_emissions_kgco2e, emissions_column, rows_with_emissions, rows_missing_emissions, skip_reason_counts, no_match_reason_counts, excluded_used_good_rows, aggregate_rows_skipped (total rows skipped so the purchases they sum are not counted twice; they are inside total_rows), confidence_bucket_counts, top_emitters (the ten largest rows) and emissions_by_ef (the 15 largest factors).

read_emission_factor_mapping_result_file#

Returns result rows as objects, so the client can filter, count and sum them. The row shape depends on the factors the job matched on and on your key.

A partner key, or a job that did not match on open_ef factors, gets the uploaded columns plus a fixed set of 106 pipeline columns. A column the file lacks is left out.

• Nine describe the line: ef_library (the route that ran, not a library), confidence, no_match_reason, reformulation_item_nature, review_reason, basis_fallback, agent_reasoning, detected_quantities and quantity_conversion_detail.
• Eighty are sixteen columns repeated for each of the five ranked candidates, named final_top_1_ to final_top_5_: ef_fingerprint, ef_keyword, ef_attribute, ef_unit, ef_data_source (the library the factor came from), ef_value_kgco2e_per_native_unit, quantity_in_ef_native_unit, magnitude_applied, total_emissions_kgco2e, total_emissions_skip_reason, score, freight_distance_basis, freight_reconciled_tonne_km, dataset_name, dataset_version and value_withheld_reason (licence or pending; a withheld value is null and left out of every sum, never 0). Rank 1 is the match the job chose; ranks 2 to 5 are the alternatives it weighed, which is what lets you re-rank a line without running the job again.
• Two explain the library choice: final_top_1_library_choice_reason (why rank 1 beat a candidate from another library, region or year) and final_top_1_value_outlier (true when rank 1's value sits far from its activity group's centre).
• Fifteen identify the product and place the line in a GHG scope: product_registry_supplier, product_registry_product, product_registry_product_id, classifier_variant, classifier_offering_kind, and ten ghg_* columns, such as ghg_scope_slots and ghg_scope_state.

When an open_ef job is read with a partner key, each row also carries final_top_1_open_ef_slug, final_top_1_open_ef_source_key, final_top_1_open_ef_release, final_top_1_open_ef_region_code and final_top_1_open_ef_boundary_preset.

An open_ef job read with any other key, OAuth sign-in included, returns the API's /v2/ row instead: row_index, the uploaded columns, flat final_top_1_ columns on the factor API's names (final_top_1_slug, final_top_1_factor_api_url, final_top_1_library, final_top_1_unit_code, final_top_1_value_co2e_normalized, final_top_1_quantity_in_factor_unit and more), the nine line columns above, and candidates, a list of up to five ranked factor objects.

Inputs.

Output. job_id, filename, row_count (before truncation), columns, rows (null is empty or no match), truncated and truncation_limit, as in read_procurement_input_file.

list_emission_factor_mapping_jobs#

Lists your recent jobs, newest first. Use it to recover a lost job_id.

Inputs.

Output. jobs, an array with job_id, status, created_at, started_at, finished_at, processed_rows, total_rows, filename and error_message per job. filename is the name of the uploaded file.

Widget-only tools#

These three are declared for the in-chat widgets. A host that honours the declaration keeps them away from the model, and a model should not call them.

upload_inline_file#

The upload widget sends a picked file's bytes through the host with this tool, so the bytes never enter the conversation.

Returns upload_id, filename, content_type and bytes_stored.

get_upload_status#

The widget calls this when a conversation reopens, to redraw a finished upload. Read-only.

Inputs: upload_id and upload_token, both required. Returns upload_id, is_resolved, and once the bytes have landed filename, content_type and bytes_stored (all null before).

download_emission_factor_mapping_result_file#

The dashboard's download button fetches the result file with this tool. A model shares download_url from get_emission_factor_mapping_result instead.

Input: job_id, required. Returns job_id, filename, mime_type and base64_content.

Related#

• Connect over MCP
• Call the API
• API reference: the generated contract for the same /v2/ endpoints the tools call, with a console that sends a real request to the sandbox or production from your browser, using your own key.