qlim8 MCP Tools Reference

Full reference for all 17 tools exposed by the qlim8 MCP server. For setup and connection examples see the MCP Quickstart.

All tool names, descriptions, and parameter names are in English and optimised for LLM consumption. All dates are ISO 8601 UTC. All CO2e values are in kilograms (kg) unless noted.

Contents

Layer 1 — Core

get_emissions_summary
list_emissions
get_emission_lineage
list_activities
list_reports
get_report_status
generate_report

Layer 2 — Strategic

list_targets
create_target
list_emission_factors
get_factor_citations
list_suppliers
get_value_chain_coverage
get_value_chain_exposure

Layer 3 — Infrastructure

list_webhooks
create_webhook
get_webhook_deliveries

Layer 1 — Core

get_emissions_summary

Layer 1 · Required scope: emissions:read

Returns total CO2e (market-based, in kg) aggregated by scope for this tenant. Use this to answer questions about total emissions, scope 1/2/3 breakdown, or year-over-year comparisons.

Input schema

Parameter	Type	Required	Description
from	string	No	ISO 8601 datetime, filter on transaction date start, e.g. "2024-01-01T00:00:00Z"
to	string	No	ISO 8601 datetime, filter on transaction date end, e.g. "2024-12-31T23:59:59Z"

Example output

{
  "total_co2e_kg": 142300.5,
  "by_scope": {
    "1": 12000.0,
    "2": 45000.0,
    "3": 85300.5
  },
  "entry_count": 847
}

list_emissions

Layer 1 · Required scope: emissions:read

Returns a cursor-paginated list of emission entries (each linked to an invoice/activity). Use for detailed audits or exporting raw emission data. Call repeatedly with next_cursor to page through all results.

Input schema

Parameter	Type	Required	Description
from	string	No	ISO 8601 datetime filter on transaction date start
to	string	No	ISO 8601 datetime filter on transaction date end
scope	"1" \| "2" \| "3"	No	Filter to a GHG scope: "1" (direct), "2" (electricity), "3" (value chain)
cursor	string	No	Opaque cursor from a previous next_cursor response field
limit	integer	No	Results per page, 1–200 (default 25)

Example output

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "scope": "3",
      "co2e_market_based_kg": 1250.3,
      "co2e_location_based_kg": 1301.7,
      "activity_split_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "created_at": "2024-03-15T14:22:00.000Z"
    }
  ],
  "next_cursor": "eyJrIjoiMjAyNC0wMy0xNVQxNDoyMjowMC4wMDBaIiwiaS..."
}

get_emission_lineage

Layer 1 · Required scope: emissions:read

Returns the full data lineage for a single emission entry: the source invoice/activity, the emission factor used, category change history, and cryptographic audit event hashes for independent verification.

Input schema

Parameter	Type	Required	Description
id	string (uuid)	Yes	UUID of the emission entry to trace

Example output

{
  "emission_entry": {
    "id": "550e8400-...",
    "scope": "3",
    "co2e_market_based_kg": 1250.3,
    "co2e_location_based_kg": 1301.7,
    "calculated_at": "2024-03-15T14:22:00.000Z",
    "calculation_log": { "categoryName": "Road freight", "emissionFactorRegion": "DK", "emissionFactorYear": 2023 }
  },
  "activity_split": {
    "id": "7c9e6679-...",
    "category_mapped": "Road freight",
    "amount_allocated_dkk": 45000.0,
    "quantity_input": 2500.0,
    "unit_input": "km",
    "is_green_power": false,
    "ai_confidence": 0.97,
    "created_at": "2024-03-15T14:20:00.000Z"
  },
  "activity": {
    "id": "abc12345-...",
    "external_id": "INV-2024-0312",
    "transaction_date": "2024-03-12T00:00:00.000Z",
    "description": "Freight invoice March 2024",
    "amount": 45000.0,
    "currency": "DKK",
    "ingested_at": "2024-03-15T14:00:00.000Z"
  },
  "emission_factor": {
    "id": "ef123-...",
    "source": "Energistyrelsen 2023",
    "category": "Road freight",
    "region": "DK",
    "year": 2023,
    "factor_value": 0.0501,
    "unit_numerator": "kg CO2e",
    "unit_denominator": "km"
  },
  "history": {
    "category_changes": [],
    "audit_events": [
      { "id": "ae001-...", "seq": 1, "timestamp": "2024-03-15T14:22:00.000Z", "action": "emission.calculated", "actor_id": null, "hash": "a3f8b2...", "prev_hash": "000000..." }
    ]
  }
}

list_activities

Layer 1 · Required scope: activities:read

Returns a cursor-paginated list of activities (invoices and transactions) for this tenant. Each activity is a source document that may produce one or more emission entries after categorization.

Input schema

Parameter	Type	Required	Description
from	string	No	ISO 8601 datetime filter on transaction date start
to	string	No	ISO 8601 datetime filter on transaction date end
cursor	string	No	Opaque cursor from a previous next_cursor
limit	integer	No	Results per page, 1–200 (default 25)

Example output

{
  "data": [
    {
      "id": "abc12345-...",
      "department_id": null,
      "data_source_id": "ds001-...",
      "external_id": "INV-2024-0312",
      "transaction_date": "2024-03-12T00:00:00.000Z",
      "description": "Freight invoice March 2024",
      "amount": 45000.0,
      "currency": "DKK",
      "is_sandbox": false,
      "created_at": "2024-03-15T14:00:00.000Z"
    }
  ],
  "next_cursor": null
}

list_reports

Layer 1 · Required scope: reports:read

Returns all previously generated compliance reports for this tenant (VSME, CSRD, etc.).

Input schema: None

Example output

[
  {
    "id": "rpt001-...",
    "report_year": 2024,
    "standard_type": "vsme_basic",
    "filename": "vsme_basic_2024.pdf",
    "file_size_bytes": 245678,
    "created_at": "2025-01-10T09:00:00.000Z"
  }
]

get_report_status

Layer 1 · Required scope: reports:read

Returns the status of a report render job. Poll until status is "completed" or "failed".

Input schema

Parameter	Type	Required	Description
id	string (uuid)	Yes	UUID of the report job (from generate_report) or a generated report

Example output

{
  "id": "job001-...",
  "status": "completed",
  "report_year": 2024,
  "standard_type": "vsme_basic",
  "queued_at": "2025-01-10T08:50:00.000Z",
  "started_at": "2025-01-10T08:50:05.000Z",
  "completed_at": "2025-01-10T08:51:30.000Z",
  "failed_at": null,
  "failure_reason": null,
  "generated_report_id": "rpt001-..."
}

Status values: queued → running → completed | failed

generate_report

Layer 1 · Required scope: reports:generate

Triggers an async report render job. Returns a job ID for polling with get_report_status. Idempotent for in-flight jobs.

Input schema

Parameter	Type	Required	Description
report_year	integer	Yes	Calendar year the report covers, e.g. 2024
standard_type	string	Yes	"vsme_basic", "vsme_bp", "vsme_comprehensive", or "csrd"
format	"pdf" \| "xlsx"	No	Output format (default: "pdf")

Example output

{
  "id": "job001-...",
  "status": "queued",
  "report_year": 2024,
  "standard_type": "vsme_basic",
  "queued_at": "2025-01-10T08:50:00.000Z",
  "started_at": null,
  "completed_at": null,
  "failed_at": null,
  "failure_reason": null,
  "generated_report_id": null
}

Layer 2 — Strategic

list_targets

Layer 2 · Required scope: targets:read

Returns all CO2 reduction targets for this tenant.

Input schema: None

Example output

[
  {
    "id": "tgt001-...",
    "name": "Science-Based Target 2030",
    "baseline_year": 2019,
    "baseline_emissions": 500.0,
    "target_year": 2030,
    "target_reduction_percent": 46.2,
    "scope": "all",
    "category": null,
    "description": "Aligned with 1.5°C pathway",
    "is_active": true,
    "created_at": "2023-06-01T10:00:00.000Z"
  }
]

create_target

Layer 2 · Required scope: targets:write

Creates a new CO2 reduction target. Returns the created target with its assigned ID.

Input schema

Parameter	Type	Required	Description
name	string	Yes	Display name, max 120 chars
baseline_year	integer	Yes	Reference year, e.g. 2019
baseline_emissions	number	Yes	Total CO2e in baseline year (tonnes), ≥ 0
target_year	integer	Yes	Year to achieve the reduction, e.g. 2030
target_reduction_percent	number	Yes	Percentage reduction, 0–100
scope	string	No	"1", "2", "3", "1+2", or "all"
category	string	No	Emission category, e.g. "Purchased electricity"
description	string	No	Narrative, max 2000 chars

Example output

{
  "id": "tgt002-...",
  "name": "Science-Based Target 2030",
  "baseline_year": 2019,
  "baseline_emissions": 500.0,
  "target_year": 2030,
  "target_reduction_percent": 46.2,
  "scope": "all",
  "is_active": true,
  "created_at": "2026-05-15T09:00:00.000Z"
}

list_emission_factors

Layer 2 · Required scope: factors:read

Returns the emission factor catalog. Each factor maps category + region + year to kg CO2e per unit.

Input schema

Parameter	Type	Required	Description
category	string	No	Filter by category name, e.g. "Electricity, Denmark"
region	string	No	Filter by region code, e.g. "DK", "EU", "WORLD"
cursor	string	No	Opaque cursor from next_cursor
limit	integer	No	1–200 (default 25)

Example output

{
  "data": [
    {
      "id": "ef001-...",
      "source": "Energistyrelsen 2023",
      "category": "Electricity, Denmark",
      "region": "DK",
      "year": 2023,
      "factor_value": 0.132,
      "unit_numerator": "kg CO2e",
      "unit_denominator": "kWh"
    }
  ],
  "next_cursor": null
}

get_factor_citations

Layer 2 · Required scope: factors:read

Returns how many of this tenant's emission entries used a specific emission factor, plus a sample of entry IDs. Use for auditor self-service.

Input schema

Parameter	Type	Required	Description
id	string (uuid)	Yes	UUID of the emission factor

Example output

{
  "factor": { "id": "ef001-...", "source": "Energistyrelsen 2023", "category": "Electricity, Denmark", "region": "DK", "year": 2023, "factor_value": 0.132, "unit_numerator": "kg CO2e", "unit_denominator": "kWh" },
  "citation_count": 142,
  "sample_emission_entry_ids": ["550e8400-...", "7c9e6679-..."]
}

list_suppliers

Layer 2 · Enterprise (supplyChain feature) · Required scope: suppliers:read

Returns all Scope 3 supplier connections including disclosure status. Enterprise plan required.

Input schema

Parameter	Type	Required	Description
year	integer	No	Filter to a specific report year, e.g. 2024

Example output

[
  {
    "id": "sup001-...",
    "supplier_identifier": "12345678",
    "supplier_country": "DK",
    "supplier_name": "Acme Transport A/S",
    "supplier_industry": "Road freight",
    "report_year": 2024,
    "status": "active",
    "enterprise_trade_amount": 450000.0,
    "enterprise_trade_currency": "DKK",
    "invited_email": "supplier@acme.dk",
    "accepted_at": "2024-02-01T12:00:00.000Z",
    "revoked_at": null
  }
]

get_value_chain_coverage

Layer 2 · Enterprise · Required scope: suppliers:read

Returns the percentage of total supplier spend covered by active Scope 3 disclosures. Enterprise plan required.

Input schema

Parameter	Type	Required	Description
year	integer	No	Report year (defaults to most recent year with data)

Example output

{
  "report_year": 2024,
  "total_supplier_count": 45,
  "active_supplier_count": 32,
  "coverage_pct": 71.1,
  "total_trade_amount": 12500000.0,
  "covered_trade_amount": 8887500.0
}

get_value_chain_exposure

Layer 2 · Enterprise · Required scope: suppliers:read

Returns suppliers sorted by trade amount descending — shows which suppliers represent the largest Scope 3 risk. Enterprise plan required.

Input schema

Parameter	Type	Required	Description
year	integer	No	Report year (defaults to most recent year with data)

Example output

{
  "report_year": 2024,
  "suppliers": [
    { "supplier_identifier": "12345678", "supplier_name": "Acme Transport A/S", "supplier_country": "DK", "status": "active", "trade_amount": 450000.0 },
    { "supplier_identifier": "87654321", "supplier_name": "BuildCo A/S", "supplier_country": "DK", "status": "pending", "trade_amount": 320000.0 }
  ]
}

Layer 3 — Infrastructure

list_webhooks

Layer 3 · Required scope: webhooks:read

Returns all webhook subscriptions for this tenant.

Input schema: None

Example output

[
  {
    "id": "wh001-...",
    "url": "https://your-app.com/webhooks/qlim8",
    "description": "Production webhook",
    "events": ["emission.created", "report.completed"],
    "environment": "live",
    "is_active": true,
    "last_delivered_at": "2024-03-15T14:22:00.000Z",
    "last_failed_at": null,
    "deactivated_reason": null,
    "signing_secret_last_four": "Xk9p",
    "created_at": "2024-01-01T00:00:00.000Z"
  }
]

create_webhook

Layer 3 · Required scope: webhooks:manage

Creates a new webhook subscription. Returns the signing secret once — store it securely. Available event types (partial list — see full list at GET /api/mcp/schema): emission.created, emission.updated, activity.created, report.completed, supplier.invited, supplier.accepted, target.created.

Input schema

Parameter	Type	Required	Description
url	string (url)	Yes	HTTPS endpoint, e.g. "https://your-app.com/webhooks/qlim8"
events	string[]	Yes	One or more event types to subscribe to
description	string	No	Human-readable label, max 200 chars
environment	"live" \| "sandbox"	No	Defaults to the key's environment

Example output

{
  "id": "wh001-...",
  "url": "https://your-app.com/webhooks/qlim8",
  "events": ["emission.created"],
  "environment": "live",
  "is_active": true,
  "signing_secret": "whsec_abc123...",
  "signing_secret_last_four": "123.",
  "created_at": "2024-03-15T14:00:00.000Z"
}

Example output shows signing_secret only once. Use it to verify incoming payloads — see qlim8 docs for HMAC-SHA256 verification snippets.

get_webhook_deliveries

Layer 3 · Required scope: webhooks:read

Returns the 100 most recent delivery attempts for a webhook, newest first.

Input schema

Parameter	Type	Required	Description
webhook_id	string (uuid)	Yes	UUID of the webhook subscription

Example output

[
  {
    "id": "del001-...",
    "webhook_id": "wh001-...",
    "event": "emission.created",
    "schema_version": "2026-05",
    "status": "delivered",
    "attempt_count": 1,
    "last_attempt_at": "2024-03-15T14:22:05.000Z",
    "last_response_status": 200,
    "last_response_latency_ms": 87,
    "next_attempt_at": null,
    "delivered_at": "2024-03-15T14:22:05.000Z",
    "created_at": "2024-03-15T14:22:00.000Z"
  }
]

Delivery status values: pending, delivered, failed, retrying

Prefer REST?

Every MCP tool has a corresponding REST endpoint under /api/v1. Same auth, same rate limits.

REST API endpoints →