> ## 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 Quickstart

> Connect AI assistants to your Dcycle operational data

## Overview

The Dcycle MCP Server integrates with Claude, ChatGPT, GitHub Copilot, Gemini CLI, Cursor, Windsurf, and other MCP-compatible AI assistants. The quickest way to connect is the **remote server** at `https://mcp.dcycle.io` — no installation required.

***

## Remote Mode

Connect directly to the hosted Dcycle MCP server. Authentication is handled via OAuth 2.0 — Claude will open a browser window to log in with your Dcycle account.

### Claude Desktop

Ask your Claude admin to add a custom connector with:

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

On first use Claude will prompt you to log in.

### Claude Code

```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.

### VS Code (GitHub Copilot)

Add a `.vscode/mcp.json` file to your project root:

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

VS Code will handle OAuth automatically on first use. Alternatively, configure globally via **Settings → MCP → Add Server**.

### ChatGPT Desktop

1. Open ChatGPT Desktop → **Settings** → **Connections**
2. Click **Add MCP server**
3. Enter the server URL: `https://mcp.dcycle.io/mcp`

ChatGPT will initiate the OAuth browser flow automatically.

### Microsoft Copilot Studio

1. Open your agent → **Tools** → **Add a tool** → **New tool** → **Model Context Protocol**
2. Set **Server URL** to `https://mcp.dcycle.io/mcp`
3. Set **Authentication type** to **OAuth 2.0** → **Dynamic discovery** (the server exposes the standard OAuth metadata endpoint)
4. Click **Create**, then **Add to agent**

Requires Generative Orchestration to be enabled on the agent.

### OpenAI Responses API

Pass the MCP server directly in the `tools` parameter. You'll need a Dcycle API key (obtainable from [Settings → API](https://app.dcycle.io/settings/api)) to use as the Bearer token:

<Tabs>
  <Tab title="Python">
    ```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    from openai import OpenAI

    client = OpenAI()
    response = client.responses.create(
        model="gpt-4.1",
        tools=[
            {
                "type": "mcp",
                "server_label": "dcycle",
                "server_url": "https://mcp.dcycle.io/mcp",
                "headers": {"Authorization": "Bearer <your_dcycle_api_key>"},
                "require_approval": "never",
            }
        ],
        input="Show me my organization overview",
    )
    print(response.output_text)
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
    import OpenAI from "openai";

    const client = new OpenAI();
    const response = await client.responses.create({
      model: "gpt-4.1",
      tools: [
        {
          type: "mcp",
          server_label: "dcycle",
          server_url: "https://mcp.dcycle.io/mcp",
          headers: { Authorization: "Bearer <your_dcycle_api_key>" },
          require_approval: "never",
        },
      ],
      input: "Show me my organization overview",
    });
    console.log(response.output_text);
    ```
  </Tab>
</Tabs>

### Manus

Manus supports Streamable HTTP MCP servers with custom headers. Use a Dcycle API key encoded as a bearer token — no browser OAuth required.

In your Manus agent configuration, add the MCP server under `mcpServers`:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "mcpServers": {
    "Dcycle": {
      "type": "streamableHttp",
      "url": "https://mcp.dcycle.io/mcp",
      "headers": {
        "Authorization": "Bearer dcy_<your_api_key>"
      }
    }
  }
}
```

Replace `<your_api_key>` with an API key generated in [Settings → API](https://app.dcycle.io/settings/api).

After connecting, call `list_my_organizations` to see which organizations you have access to, then `set_default_organization` with the desired organization ID before querying data.

### Cursor

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 that Cursor can connect to. OAuth is handled in the browser on first run.

### Windsurf (Codeium)

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.

### Gemini CLI

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 with `/mcp auth dcycle`.

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

***

## Local Mode

Run the server on your own machine using a Dcycle API key. Useful for automation or environments without browser access.

### Prerequisites

* Python 3.10+
* `uv` installed (`pip install uv`)
* **Dcycle API Key** — get it from [Settings > API](https://app.dcycle.io/settings/api)
* **Organization ID** — your organization UUID from Dcycle

### Claude Desktop

<Tabs>
  <Tab title="macOS">
    Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "mcpServers": {
        "dcycle": {
          "command": "uvx",
          "args": ["dcycle-mcp"],
          "env": {
            "DCYCLE_API_KEY": "your_api_key",
            "DCYCLE_ORG_ID": "your_org_uuid"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Windows">
    Edit `%APPDATA%\Claude\claude_desktop_config.json`:

    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "mcpServers": {
        "dcycle": {
          "command": "uvx",
          "args": ["dcycle-mcp"],
          "env": {
            "DCYCLE_API_KEY": "your_api_key",
            "DCYCLE_ORG_ID": "your_org_uuid"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

### Claude Code

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
claude mcp add dcycle -- uvx dcycle-mcp
```

Or add a `.mcp.json` file to your project root:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "mcpServers": {
    "dcycle": {
      "command": "uvx",
      "args": ["dcycle-mcp"],
      "env": {
        "DCYCLE_API_KEY": "your_api_key",
        "DCYCLE_ORG_ID": "your_org_uuid"
      }
    }
  }
}
```

### Environment Variables

| Variable         | Required    | Default                 | Description               |
| ---------------- | ----------- | ----------------------- | ------------------------- |
| `DCYCLE_API_KEY` | Yes         | —                       | Your Dcycle API key       |
| `DCYCLE_ORG_ID`  | Recommended | —                       | Default organization UUID |
| `DCYCLE_API_URL` | No          | `https://api.dcycle.io` | API base URL              |

***

## Verify the Connection

Ask Claude:

```
"Check my Dcycle connection status"
```

Claude will call `get_connection_status` and show your organization metrics — facilities, vehicles, employees, and more.

***

## Example Queries

### Organization Overview

```
"Show me my organization tree"
"How many facilities, vehicles, and employees do we have?"
```

### Energy & Invoices

```
"List our electricity invoices from the last quarter"
"Which invoices have the highest CO2 emissions?"
```

### Fleet

```
"Show me our vehicle fleet"
"Which vehicles use diesel?"
```

### Supply Chain

```
"List our purchases with the highest emissions"
"Show supplier-specific purchases"
```

### Business Travel

```
"Show business travel records by train"
"What were the highest-emission trips last year?"
```

### Logistics

```
"Show our recent shipping requests and their emissions"
"What are the top routes by kgCO2e?"
```

***

## Tips for Better Results

<AccordionGroup>
  <Accordion title="Specify the organization" icon="building">
    In remote mode the server uses the organization linked to your account. In local mode, set `DCYCLE_ORG_ID` as the default or pass `organization_id` to any tool.
  </Accordion>

  <Accordion title="Use filters" icon="filter">
    Most list tools support filters: `status`, `type`, date ranges, and search. Ask Claude to filter — it will use the right parameters.
  </Accordion>

  <Accordion title="Ask follow-up questions" icon="comments">
    Claude maintains context. After listing vehicles, ask "which ones use diesel?" or "show me the top emitters".
  </Accordion>

  <Accordion title="Request specific formats" icon="table">
    Ask for tables, comparisons, or summaries: "show this as a table" or "summarize the key findings".
  </Accordion>
</AccordionGroup>

***

## Troubleshooting

### Remote mode: "OAuth authentication failed"

* Make sure you're logging in with your Dcycle account credentials
* Check that your account has access to the organization you're querying

### Local mode: "MCP server not found"

* Ensure Python 3.10+ is installed
* Verify `uvx` is available: `uvx --version`
* Check the configuration file is valid JSON

### Local mode: "Authentication failed"

* Verify your API key at [app.dcycle.io/settings/api](https://app.dcycle.io/settings/api)
* Ensure `DCYCLE_API_KEY` is correctly set in the config

### "organization\_id is required"

* Remote mode: your account must be linked to an organization
* Local mode: set `DCYCLE_ORG_ID` in your env config

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Organization Tools" icon="building" href="/mcp/organizations">
    Explore organization management capabilities
  </Card>

  <Card title="Vehicle Tools" icon="car" href="/mcp/vehicles">
    Explore fleet data
  </Card>

  <Card title="Invoice Tools" icon="file-invoice" href="/mcp/invoices">
    Query energy invoices
  </Card>

  <Card title="Reference Data" icon="database" href="/mcp/resources">
    Available reference resources
  </Card>
</CardGroup>