> ## Documentation Index
> Fetch the complete documentation index at: https://code.dcycle.io/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Overview

> Connect AI assistants to your Dcycle operational data

# Dcycle MCP Server

The Dcycle MCP (Model Context Protocol) Server lets AI assistants query and manage your operational data directly — organizations, facilities, invoices, vehicles, employees, workforce, purchases, travel, logistics, emissions, projects, decarbonization plans, LCA, custom KPIs, and more. With 102 tools (78 read + 24 write), 6 reference resources, and 3 guided workflow prompts, you can analyze environmental impact, track reduction progress, create operational records, and generate compliance reports through natural language.

## What is MCP?

[MCP](https://modelcontextprotocol.io) is an open standard created by Anthropic that lets AI assistants securely connect to external data sources. Think of it like connecting Google Calendar to Claude — but for your operational data.

## Connection Modes

The Dcycle MCP server supports two modes:

<CardGroup cols={2}>
  <Card title="Remote (Recommended)" icon="cloud" href="/mcp/quickstart#remote-mode">
    Connect directly to `https://mcp.dcycle.io` — no installation needed. Authenticate with your Dcycle account via OAuth 2.0.
  </Card>

  <Card title="Local (stdio)" icon="terminal" href="/mcp/quickstart#local-mode">
    Run the server on your own machine with a Dcycle API key. Useful for automation or custom deployments.
  </Card>
</CardGroup>

## What Can You Do?

<CardGroup cols={3}>
  <Card title="Organizations" icon="building">
    Hierarchy, metrics, and group structure
  </Card>

  <Card title="Facilities" icon="location-dot">
    Offices, factories, warehouses with details
  </Card>

  <Card title="Invoices" icon="file-invoice">
    Electricity, gas, water invoices with co2e
  </Card>

  <Card title="Vehicles" icon="car">
    Fleet data — fuel, ownership, emissions
  </Card>

  <Card title="Employees" icon="users">
    Employees and commuting data
  </Card>

  <Card title="Workforce" icon="people-group">
    ESG social data — demographics, contracts, locations
  </Card>

  <Card title="Purchases" icon="cart-shopping">
    Scope 3 purchased goods & services
  </Card>

  <Card title="Business Travel" icon="plane">
    Travel records by transport type
  </Card>

  <Card title="Hotel Stays" icon="hotel">
    Accommodation stays with emissions
  </Card>

  <Card title="Transports" icon="route">
    Upstream/downstream transport records
  </Card>

  <Card title="Logistics" icon="truck">
    Shipping, hubs, clients, and reports
  </Card>

  <Card title="Wastes" icon="trash-can">
    Waste records by facility
  </Card>

  <Card title="Waste Water" icon="droplet">
    Treatment records, discharge, co2e
  </Card>

  <Card title="Sold Products" icon="box-open">
    Products, periods, per-country emissions
  </Card>

  <Card title="Files" icon="file">
    Uploaded files and processing status
  </Card>

  <Card title="Emissions" icon="smog">
    GHG emissions, historical trends, emission factors
  </Card>

  <Card title="Projects" icon="clipboard-list">
    ESG projects, tasks, and activity feeds
  </Card>

  <Card title="Dashboards" icon="chart-line">
    Saved report dashboards with widgets
  </Card>

  <Card title="Decarbonization" icon="arrow-trend-down">
    Plans, targets, actions, and baselines
  </Card>

  <Card title="Custom KPIs" icon="gauge">
    KPI datasets, campaigns, and values
  </Card>

  <Card title="LCA" icon="leaf">
    Life Cycle Assessment portfolios and impacts
  </Card>

  <Card title="Elastic Data" icon="table">
    Custom datasets with flexible schemas
  </Card>

  <Card title="Compliance" icon="scale-balanced">
    Environmental legislation and regulations
  </Card>

  <Card title="Reference Data" icon="database">
    GHG scopes, categories, sectors
  </Card>
</CardGroup>

## Available Tools (93)

<Accordion title="Organization & Meta">
  | Tool                       | Description                              |
  | -------------------------- | ---------------------------------------- |
  | `get_connection_status`    | Verify connection and show data overview |
  | `list_my_organizations`    | List accessible organizations            |
  | `set_default_organization` | Set default org for subsequent calls     |
  | `get_organization_metrics` | Counts of all data types                 |
  | `get_organization_tree`    | Parent-child org hierarchy               |
  | `get_organization_canvas`  | All orgs with connections                |
</Accordion>

<Accordion title="Facilities & Invoices">
  | Tool              | Description                                      |
  | ----------------- | ------------------------------------------------ |
  | `list_facilities` | List facilities with name, country, type filters |
  | `get_facility`    | Get facility details by ID                       |
  | `create_facility` | **Write** — Create a new facility                |
  | `update_facility` | **Write** — Update an existing facility          |
  | `list_invoices`   | Energy invoices with filters                     |
  | `create_invoice`  | **Write** — Create a new energy invoice          |
  | `update_invoice`  | **Write** — Update an existing invoice           |
</Accordion>

<Accordion title="Fleet, Employees & Procurement">
  | Tool                          | Description                                                     |
  | ----------------------------- | --------------------------------------------------------------- |
  | `list_vehicles`               | Fleet vehicles with fuel and co2e                               |
  | `create_vehicle`              | **Write** — Create a new vehicle                                |
  | `update_vehicle`              | **Write** — Update an existing vehicle                          |
  | `list_employees`              | Employees and commuting                                         |
  | `create_employee`             | **Write** — Create a new employee                               |
  | `update_employee`             | **Write** — Update an existing employee                         |
  | `list_workforce`              | Own workforce — demographics, contracts, locations (ESG social) |
  | `list_workforce_absenteeisms` | Absenteeism and workplace accident records                      |
  | `list_workforce_trainings`    | Training records — type, hours, dates (ESG social)              |
  | `get_workforce_contracts`     | Contracts for a workforce employee (start/end dates)            |
  | `get_workforce_remunerations` | Remunerations for a contract (amount, currency, period)         |
  | `list_purchases`              | Purchased goods & services                                      |
  | `create_purchase`             | **Write** — Create a purchase record                            |
  | `update_purchase`             | **Write** — Update an existing purchase                         |
  | `list_business_travels`       | Travel records with co2e                                        |
  | `create_business_travel`      | **Write** — Create a business travel record                     |
  | `update_business_travel`      | **Write** — Update a business travel record                     |
  | `list_hotel_stays`            | Hotel stay records                                              |
  | `create_hotel_stay`           | **Write** — Create a hotel stay record                          |
  | `update_hotel_stay`           | **Write** — Update an existing hotel stay                       |
  | `list_transports`             | Upstream/downstream transports                                  |
  | `create_transport`            | **Write** — Create a transport record                           |
  | `update_transport`            | **Write** — Update an existing transport                        |
</Accordion>

<Accordion title="Logistics">
  | Tool                       | Description                           |
  | -------------------------- | ------------------------------------- |
  | `list_logistics_requests`  | Shipping with emission calculations   |
  | `create_logistics_request` | **Write** — Create a shipping request |
  | `list_logistics_clients`   | Logistics clients                     |
  | `list_logistics_hubs`      | Distribution hubs                     |
  | `get_logistics_report`     | ISO 14083 emissions report            |
  | `get_logistics_summary`    | TOC/HOC summary                       |
</Accordion>

<Accordion title="Waste, Files & Members">
  | Tool                   | Description                                 |
  | ---------------------- | ------------------------------------------- |
  | `list_wastes`          | Waste records by facility                   |
  | `create_waste`         | **Write** — Create a waste record           |
  | `update_waste`         | **Write** — Update an existing waste record |
  | `list_files`           | Uploaded files and status                   |
  | `get_file`             | File details by ID                          |
  | `list_members`         | Organization users                          |
  | `list_processing_jobs` | Processing job status                       |
</Accordion>

<Accordion title="CSRD / Double Materiality">
  | Tool                         | Description                                             |
  | ---------------------------- | ------------------------------------------------------- |
  | `list_double_materiality`    | Double Materiality topics with ESG category and scores  |
  | `list_csrd_iros`             | IROs (Impacts, Risks, Opportunities) for a given year   |
  | `get_csrd_output_data`       | Disclosure requirements grouped by code with datapoints |
  | `list_measurement_campaigns` | Measurement campaigns (reporting periods)               |
  | `list_csrd_survey_results`   | Stakeholder materiality survey scores                   |
</Accordion>

<Accordion title="PPWR (Packaging Compliance)">
  | Tool                       | Description                                              |
  | -------------------------- | -------------------------------------------------------- |
  | `list_packaging_units`     | List packaging units for a PPWR project                  |
  | `get_packaging_unit`       | Packaging unit detail — BOM, substances, recyclability   |
  | `get_packaging_compliance` | Compliance evaluation for a packaging unit               |
  | `get_project_compliance`   | Compliance summary for all units in a project            |
  | `get_packaging_gaps`       | Gap analysis with traffic-light severity                 |
  | `get_ppwr_dashboard`       | Dashboard KPIs — recycled content, compliance, suppliers |
</Accordion>

<Accordion title="Waste Water Treatments">
  | Tool                          | Description                                         |
  | ----------------------------- | --------------------------------------------------- |
  | `list_waste_water_treatments` | WWT records for a facility — paginated with filters |
  | `get_waste_water_treatment`   | WWT detail — treatment type, flow, co2e breakdown   |
</Accordion>

<Accordion title="Sold Products">
  | Tool                                | Description                             |
  | ----------------------------------- | --------------------------------------- |
  | `list_sold_products`                | Sold products with optional name filter |
  | `get_sold_product_periods`          | Date-range periods for a sold product   |
  | `get_sold_product_period_emissions` | Detailed emissions for a period         |
</Accordion>

<Accordion title="Emissions">
  | Tool                           | Description                                  |
  | ------------------------------ | -------------------------------------------- |
  | `get_greenhouse_gas_emissions` | Validated GHG emissions across 26 categories |
  | `get_use_of_product_emissions` | Scope 3 use-of-sold-products                 |
  | `get_historical_emissions`     | Year-over-year trends                        |
  | `get_total_impacts`            | Aggregated impacts by scope/category         |
  | `list_emission_factors`        | Emission factors in use                      |
</Accordion>

<Accordion title="Projects & Dashboards">
  | Tool                    | Description                        |
  | ----------------------- | ---------------------------------- |
  | `list_projects`         | ESG projects                       |
  | `get_project`           | Project details by ID              |
  | `list_project_tasks`    | Tasks within a project             |
  | `get_recent_activities` | Project activity feed              |
  | `create_project`        | **Create** a new project           |
  | `create_project_task`   | **Create** a task within a project |
  | `list_dashboards`       | Saved report dashboards            |
  | `get_dashboard`         | Dashboard with widgets             |
</Accordion>

<Accordion title="Decarbonization Plans">
  | Tool                   | Description                       |
  | ---------------------- | --------------------------------- |
  | `list_decarb_plans`    | Decarbonization plans             |
  | `get_decarb_plan`      | Plan baselines                    |
  | `list_decarb_targets`  | Reduction targets                 |
  | `create_decarb_target` | **Create** reduction target       |
  | `list_decarb_actions`  | Planned actions                   |
  | `create_decarb_action` | **Create** decarbonization action |
  | `get_decarb_perimeter` | Scope perimeter                   |
</Accordion>

<Accordion title="Custom KPIs">
  | Tool                      | Description                          |
  | ------------------------- | ------------------------------------ |
  | `list_custom_kpis`        | KPI definitions by org/facility      |
  | `get_custom_kpi`          | KPI detail with dataset context      |
  | `list_kpi_datasets`       | KPI dataset containers               |
  | `list_kpi_campaigns`      | Data collection campaigns            |
  | `get_kpi_campaign_values` | Submitted campaign values            |
  | `list_kpi_assignments`    | Facility assignments                 |
  | `submit_kpi_response`     | **Submit** values for a KPI campaign |
</Accordion>

<Accordion title="LCA, Elastic Data & Compliance">
  | Tool                    | Description                      |
  | ----------------------- | -------------------------------- |
  | `list_lcas`             | LCA portfolios                   |
  | `get_lca_dashboard`     | Impact results by EN 15804 stage |
  | `get_lca_block_impacts` | Impact by lifecycle block        |
  | `get_lca_piece_impacts` | Impact by material               |
  | `validate_lca`          | Validate LCA completeness        |
  | `list_datasets`         | Elastic datasets                 |
  | `get_dataset`           | Dataset schema                   |
  | `query_dataset`         | Query dataset records            |
  | `list_legislation`      | Environmental legislation        |
  | `get_legislation`       | Legislation details              |
</Accordion>

Most tools are **read-only**. Write tools (`create_facility`, `update_facility`, `create_purchase`, `update_purchase`, `create_business_travel`, `update_business_travel`, `create_hotel_stay`, `update_hotel_stay`, `create_transport`, `update_transport`, `create_waste`, `update_waste`, `create_decarb_target`, `create_decarb_action`, `create_project`, `create_project_task`, `submit_kpi_response`) are annotated with `readOnlyHint: false` so AI assistants can distinguish them and confirm with you before making changes.

## Resources (6)

In addition to tools, the server exposes [MCP Resources](https://modelcontextprotocol.io/docs/concepts/resources) — static reference data automatically available to the AI assistant as context.

| Resource                    | Description                                           |
| --------------------------- | ----------------------------------------------------- |
| `dcycle://scopes`           | GHG Protocol scope definitions (Scope 1, 2, 3)        |
| `dcycle://categories`       | 14 emission categories mapped to their scopes         |
| `dcycle://lca-stages`       | EN 15804 life cycle stages (A1–B7)                    |
| `dcycle://sectors`          | 25 valid organization sector values                   |
| `dcycle://pivot-dimensions` | Available dimensions for emissions analysis (dynamic) |
| `dcycle://config`           | Current MCP connection configuration                  |

See [Reference Resources](/mcp/resources) for full details and content.

## Prompts (3)

The server also provides [MCP Prompts](https://modelcontextprotocol.io/docs/concepts/prompts) — guided workflows that chain multiple tools together to produce structured reports. Each prompt accepts a `year` argument (defaults to the previous calendar year).

| Prompt                     | Description                                                                                      | Tools used                                                                                           |
| -------------------------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
| `carbon_footprint_summary` | Full carbon footprint report with scope breakdown, top categories, and reduction recommendations | `get_total_impacts`, `get_organization_metrics`, `get_greenhouse_gas_emissions`                      |
| `fleet_report`             | Fleet emissions analysis with fuel type breakdown, ownership split, and top emitters             | `list_vehicles`, `get_greenhouse_gas_emissions`, `get_total_impacts`                                 |
| `logistics_overview`       | ISO 14083 logistics report with route analysis, client breakdown, and transport mode split       | `get_logistics_summary`, `get_logistics_report`, `list_logistics_clients`, `list_logistics_requests` |

<Note>
  Prompts are activated by the AI assistant when you ask for a report — e.g. "Generate a carbon footprint summary for 2025". You don't call them directly.
</Note>

## How It Works

### Remote mode

```
You: "Show me our vehicle fleet sorted by emissions"
  ↓
Claude calls list_vehicles() via MCP (HTTPS)
  ↓
mcp.dcycle.io authenticates via your Dcycle account (OAuth 2.0)
  ↓
Dcycle API returns data
  ↓
Claude presents a readable summary
```

### Local mode (stdio)

```
You: "Show me our vehicle fleet sorted by emissions"
  ↓
Claude calls list_vehicles() via MCP (stdio)
  ↓
Dcycle MCP Server (local) authenticates via API key
  ↓
Dcycle API (api.dcycle.io) returns data
  ↓
Claude presents a readable summary
```

## Security

* **Authentication required** — You must authenticate before any data is accessible. Remote connections use OAuth 2.0 (your existing Dcycle account login); local connections require a scoped API key.
* **Your data stays yours** — All requests are scoped to organizations you already have access to in Dcycle. The MCP cannot access any org you don't have permission for.
* **No credentials stored in the AI tool** — In remote mode, your Dcycle password is entered on `app.dcycle.io`, not transmitted to the AI assistant. The AI receives only a short-lived Bearer token.
* **Industry-standard protocols** — OAuth 2.0 with PKCE for browser flows, JWT validation via RS256, and HTTPS only for the remote server (`mcp.dcycle.io`).
* **Safe by default** — Read tools are annotated with `readOnlyHint: true`. Write tools (`create_facility`, `update_facility`, `create_purchase`, `update_purchase`, `create_business_travel`, `update_business_travel`, `create_hotel_stay`, `update_hotel_stay`, `create_transport`, `update_transport`, `create_waste`, `update_waste`, `create_decarb_target`, `create_decarb_action`, `create_project`, `create_project_task`, `submit_kpi_response`) are annotated with `readOnlyHint: false` and `destructiveHint: false`, so AI assistants confirm before making changes. No delete operations are exposed.

## Compatible AI Assistants

The Dcycle MCP server works with any MCP-compatible AI assistant. Here's how to connect the most common ones:

<AccordionGroup>
  <Accordion title="Claude Desktop" icon="message-bot">
    Ask your Claude admin to add a custom connector:

    * **Name:** `Dcycle`
    * **URL:** `https://mcp.dcycle.io/mcp`

    On first use Claude will open a browser for OAuth authentication.

    For local mode with an API key, see the [Quickstart](/mcp/quickstart#local-mode).
  </Accordion>

  <Accordion title="Claude Code" icon="terminal">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    claude mcp add --transport http dcycle https://mcp.dcycle.io/mcp
    ```

    On first connection Claude Code will open a browser for OAuth authentication.

    For local mode: `claude mcp add dcycle -- uvx dcycle-mcp` (requires `DCYCLE_API_KEY` env var).
  </Accordion>

  <Accordion title="GitHub Copilot (VS Code)" icon="github">
    Requires VS Code 1.101+ with the GitHub Copilot extension. MCP tools are available in **Agent mode** only.

    Add to `.vscode/mcp.json` in your project (or open *MCP: Open User Configuration* from the command palette for a global config):

    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "servers": {
        "dcycle": {
          "type": "http",
          "url": "https://mcp.dcycle.io/mcp"
        }
      }
    }
    ```

    On first use, VS Code will open a browser window to authenticate with your Dcycle account via OAuth 2.0. Tokens are managed automatically by VS Code.

    > **Note:** The root key is `"servers"` — not `"mcpServers"` (which is the Claude Desktop format).
  </Accordion>

  <Accordion title="ChatGPT" icon="comment">
    Requires a **Pro, Plus, Business, or Enterprise** plan. Configuration is done entirely through the UI — no config file needed.

    1. Go to **Settings → Apps → Advanced settings → Developer mode** and enable it.
    2. In any chat, click **"+"** and select **Add connector**.
    3. Enter:
       * **Name:** `Dcycle`
       * **MCP Server URL:** `https://mcp.dcycle.io/mcp`
    4. On first use ChatGPT will redirect you to log in with your Dcycle account via OAuth 2.0.
  </Accordion>

  <Accordion title="Microsoft Copilot Studio" icon="microsoft">
    [Microsoft Copilot Studio](https://copilotstudio.microsoft.com) is an enterprise no-code agent builder (separate from GitHub Copilot). MCP is supported in GA and requires a Copilot Studio license with **Generative Orchestration** enabled on your agent.

    1. Open your agent and go to the **Tools** tab.
    2. Click **Add a tool → New tool → Model Context Protocol**.
    3. Fill in the wizard:
       * **Server name:** `Dcycle`
       * **Server description:** `Query Dcycle operational data — organizations, invoices, vehicles, employees, purchases, business travel, and logistics.`
       * **Server URL:** `https://mcp.dcycle.io/mcp`
    4. For **Authentication**, select **OAuth 2.0 → Dynamic discovery**. Copilot Studio auto-discovers the Dcycle authorization endpoints.
    5. Click **Create**. Copilot Studio will show a **Redirect URL** — copy it.
    6. Register that Redirect URL in your Dcycle account settings so the OAuth flow can complete.

    Copilot Studio discovers all available tools automatically at runtime. No manual tool registration is needed.

    > **Note:** Only **Streamable HTTP** transport is supported. Localhost servers are not reachable from Copilot Studio's cloud infrastructure.
  </Accordion>

  <Accordion title="Gemini CLI" icon="google">
    Add to `~/.gemini/settings.json` (global) or `.gemini/settings.json` in your project root:

    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "mcpServers": {
        "dcycle": {
          "url": "https://mcp.dcycle.io/mcp"
        }
      }
    }
    ```

    On first use Gemini CLI will open a browser for OAuth authentication. You can also trigger it manually:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    /mcp auth dcycle
    ```

    Tokens are stored at `~/.gemini/mcp-oauth-tokens.json`.

    > **Note:** Gemini in Google Workspace and Google AI Studio do not support connecting to external MCP servers. Use the [Gemini CLI](https://github.com/google-gemini/gemini-cli).
  </Accordion>

  <Accordion title="Cursor" icon="code">
    Cursor supports SSE transport only. Use `mcp-remote` as a bridge (requires Node.js):

    ```json title="~/.cursor/mcp.json" theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "mcpServers": {
        "dcycle": {
          "command": "npx",
          "args": ["mcp-remote", "https://mcp.dcycle.io/mcp"]
        }
      }
    }
    ```

    `mcp-remote` proxies the Streamable HTTP server to a local stdio process. OAuth is handled in the browser on first run.
  </Accordion>

  <Accordion title="Windsurf (Codeium)" icon="wind">
    Edit `~/.codeium/windsurf/mcp_config.json`:

    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "mcpServers": {
        "dcycle": {
          "serverUrl": "https://mcp.dcycle.io/mcp"
        }
      }
    }
    ```

    Windsurf supports OAuth 2.0 via automatic browser redirect on first connection.
  </Accordion>
</AccordionGroup>

## Getting Started

<CardGroup cols={3}>
  <Card title="Quickstart Guide" icon="rocket" href="/mcp/quickstart">
    Connect in under a minute using the remote server — no installation needed
  </Card>

  <Card title="REST API" icon="code" href="/api-reference/introduction">
    Build integrations with the REST API
  </Card>

  <Card title="CLI" icon="terminal" href="/cli/overview">
    Manage data from the command line
  </Card>
</CardGroup>