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

# MCP Integration

> Connect your Mangrove data to AI assistants using the Model Context Protocol

The Mangrove MCP server enables you to query your MRV data using natural language through AI assistants like Claude and Cursor. Instead of manually exporting data and building custom queries, you can ask questions conversationally and receive structured insights from your production, accounting, and inventory data.

## What is MCP?

The Model Context Protocol (MCP) is an open standard that enables AI assistants to securely connect to external data sources and APIs. The Mangrove MCP server implements this protocol, providing a bridge between your Mangrove account and MCP-enabled tools.

<Note>
  MCP connections are read-only and respect your existing Mangrove API permissions. All queries are authenticated using your Mangrove API key.
</Note>

## Use Cases

The MCP integration is particularly useful for:

* **Ad-hoc reporting**: Query specific metrics without building custom dashboards
* **Data validation**: Quickly audit data completeness and identify gaps
* **Trend analysis**: Ask questions about patterns across time periods or locations
* **Cross-referencing**: Correlate data across events, batches, and locations

## Available Data

The MCP server provides access to all Mangrove API endpoints. You can query:

<CardGroup cols={2}>
  <Card title="Production Data" icon="database">
    Projects, locations, feedstocks, event types, events, data points, and evidence files
  </Card>

  <Card title="Accounting & Reporting" icon="chart-line">
    Batches, ledger transactions, reports, models, and model runs
  </Card>

  <Card title="Inventory Management" icon="boxes-stacked">
    Orders, issuances, retirements, and transfers
  </Card>

  <Card title="Account Administration" icon="users-gear">
    Account settings, user roles, and custom fields
  </Card>
</CardGroup>

For detailed information about each endpoint, see the [API Reference](/api-reference/authentication) sections.

## Setup

### Prerequisites

To connect to the Mangrove MCP server, you'll need:

1. **Mangrove API Key**: Generate a read-only API key as an Account Admin in [API Settings](https://app.gomangrove.com/settings/api)
2. **MCP Auth Token**: Available in your MCP Settings
3. **MCP Server URL**: `https://mcp.gomangrove.com/mcp`

<Warning>
  Contact your Implementation Engineer to receive an MCP authentication token.
</Warning>

<Tabs>
  <Tab title="Claude Desktop">
    <Steps>
      <Step title="Locate your Claude Desktop configuration">
        The configuration file location varies by operating system:

        * **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
        * **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

        If the file doesn't exist, create it.
      </Step>

      <Step title="Add the Mangrove MCP server">
        Add the following configuration to your `claude_desktop_config.json`:

        ```json theme={null}
        {
          "mcpServers": {
            "mangrove": {
              "command": "npx",
              "args": [
                "-y",
                "mcp-remote",
                "YOUR_MCP_SERVER_URL",
                "--transport",
                "http-only",
                "--header",
                "Authorization:${AUTH_TOKEN}",
                "--header",
                "X-Mangrove-Token:${MANGROVE_API_TOKEN}"
              ],
              "env": {
                "AUTH_TOKEN": "Bearer YOUR_AUTH_TOKEN",
                "MANGROVE_API_TOKEN": "YOUR_MANGROVE_API_KEY"
              }
            }
          }
        }
        ```

        Replace the placeholders:

        * `YOUR_MCP_SERVER_URL`: Provided by your Implementation Engineer
        * `YOUR_AUTH_TOKEN`: Provided by your Implementation Engineer
        * `YOUR_MANGROVE_API_KEY`: Your API key from Mangrove API Settings
      </Step>

      <Step title="Restart Claude Desktop">
        Close and reopen Claude Desktop to load the new configuration.
      </Step>

      <Step title="Verify the connection">
        In Claude Desktop, you should now see the Mangrove MCP server available. Try a simple query:

        "What projects do I have access to in Mangrove?"
      </Step>
    </Steps>
  </Tab>

  <Tab title="Cursor IDE">
    <Steps>
      <Step title="Open Cursor settings">
        Navigate to Cursor Settings > MCP
      </Step>

      <Step title="Add a new MCP server">
        Click "Add Server" and enter the following configuration:

        ```json theme={null}
        {
          "name": "mangrove",
          "command": "npx",
          "args": [
            "-y",
            "mcp-remote",
            "YOUR_MCP_SERVER_URL",
            "--transport",
            "http-only",
            "--header",
            "Authorization:${AUTH_TOKEN}",
            "--header",
            "X-Mangrove-Token:${MANGROVE_API_TOKEN}"
          ],
          "env": {
            "AUTH_TOKEN": "Bearer YOUR_AUTH_TOKEN",
            "MANGROVE_API_TOKEN": "YOUR_MANGROVE_API_KEY"
          }
        }
        ```

        Replace the placeholders with your credentials as described in the Claude Desktop setup.
      </Step>

      <Step title="Enable the server">
        Toggle the Mangrove MCP server to "enabled" in your Cursor settings.
      </Step>

      <Step title="Test the integration">
        Open a new chat in Cursor and ask:

        "Show me all events from the last week for project \[your-project-id]"
      </Step>
    </Steps>
  </Tab>

  <Tab title="VS Code">
    VS Code has native MCP support via GitHub Copilot Chat (agent mode). You can configure the server at workspace level (`.vscode/mcp.json` — shareable with your team) or at user level (applies across all workspaces).

    <Steps>
      <Step title="Open the MCP configuration">
        Open the Command Palette (`Cmd/Ctrl+Shift+P`) and run **MCP: Open User Configuration** to edit your personal `mcp.json`, or create `.vscode/mcp.json` in your workspace root to share with teammates.
      </Step>

      <Step title="Add the Mangrove MCP server">
        Add the following to your `mcp.json`:

        ```json theme={null}
        {
          "servers": {
            "mangrove": {
              "type": "http",
              "url": "YOUR_MCP_SERVER_URL",
              "headers": {
                "Authorization": "Bearer ${input:mangrove-auth-token}",
                "X-Mangrove-Token": "${input:mangrove-api-key}"
              }
            }
          },
          "inputs": [
            {
              "id": "mangrove-auth-token",
              "type": "promptString",
              "description": "Mangrove MCP auth token (from your Implementation Engineer)",
              "password": true
            },
            {
              "id": "mangrove-api-key",
              "type": "promptString",
              "description": "Mangrove API key (from API Settings)",
              "password": true
            }
          ]
        }
        ```

        Replace `YOUR_MCP_SERVER_URL` with the URL provided by your Implementation Engineer. VS Code will prompt you for the auth token and API key the first time the server starts and store them securely.
      </Step>

      <Step title="Start the server">
        Click the **Start** action above the `"mangrove"` entry in `mcp.json`, or open Copilot Chat, switch to **Agent** mode, and select the Mangrove tools from the tool picker.
      </Step>

      <Step title="Test the integration">
        In Copilot Chat agent mode, ask:

        "What projects do I have access to in Mangrove?"
      </Step>
    </Steps>
  </Tab>

  <Tab title="Claude Code">
    [Claude Code](https://claude.com/claude-code) is Anthropic's CLI agent. It can connect to the Mangrove MCP server directly using the `claude mcp add` command.

    <Steps>
      <Step title="Add the Mangrove MCP server">
        From any terminal, run:

        ```bash theme={null}
        claude mcp add --transport http mangrove \
          --scope user \
          --header "Authorization: Bearer YOUR_AUTH_TOKEN" \
          --header "X-Mangrove-Token: YOUR_MANGROVE_API_KEY" \
          YOUR_MCP_SERVER_URL
        ```

        Replace the placeholders:

        * `YOUR_MCP_SERVER_URL`: Provided by your Implementation Engineer
        * `YOUR_AUTH_TOKEN`: Provided by your Implementation Engineer
        * `YOUR_MANGROVE_API_KEY`: Your API key from Mangrove API Settings

        The `--scope user` flag makes the server available in all your Claude Code projects. Omit it to install only for the current project.
      </Step>

      <Step title="Verify the connection">
        In any Claude Code session, run `/mcp` to confirm the `mangrove` server is connected, then ask:

        "What projects do I have access to in Mangrove?"
      </Step>
    </Steps>
  </Tab>

  <Tab title="OpenAI Codex CLI">
    [Codex CLI](https://developers.openai.com/codex) is OpenAI's terminal agent. It supports remote MCP servers with static Bearer tokens and custom headers through its TOML config.

    <Steps>
      <Step title="Set environment variables for your secrets">
        Add to your shell profile (`~/.zshrc`, `~/.bashrc`, etc.):

        ```bash theme={null}
        export MANGROVE_AUTH_TOKEN="YOUR_AUTH_TOKEN"
        export MANGROVE_API_TOKEN="YOUR_MANGROVE_API_KEY"
        ```

        Reload your shell or run `source ~/.zshrc` after editing.
      </Step>

      <Step title="Add the server to ~/.codex/config.toml">
        Add the following block to `~/.codex/config.toml` (create the file if it doesn't exist):

        ```toml theme={null}
        [mcp_servers.mangrove]
        url = "YOUR_MCP_SERVER_URL"
        bearer_token_env_var = "MANGROVE_AUTH_TOKEN"
        env_http_headers = { "X-Mangrove-Token" = "MANGROVE_API_TOKEN" }
        ```

        Replace `YOUR_MCP_SERVER_URL` with the URL from your Implementation Engineer. Codex automatically adds `Authorization: Bearer ${MANGROVE_AUTH_TOKEN}` from the env var.
      </Step>

      <Step title="Test the integration">
        Start a Codex session and ask:

        "What projects do I have access to in Mangrove?"
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Example Prompts

Once connected, you can use natural language to query your Mangrove data. Here are example queries organized by common use cases:

### Production & Operations

```
"Show me all events from project abc123 in the last 30 days that are missing data points"

"What locations are associated with project xyz789 and when was the last event recorded at each?"
```

### Accounting & Compliance

```
"List all batches created in Q4 2024 with their CI scores, grouped by feedstock type"

"Which events from location loc_xyz have missing evidence files that I need for the upcoming audit?"
```

### Analysis & Insights

```
"Compare the average mass flow rates across my three production locations over the past quarter"

"Show me the trend in CI scores for corn feedstock over the last 6 months"
```

### Inventory & Credits

```
"What's the total volume of credits issued, retired, and transferred in 2024 for project abc123?"

"Show me all pending orders and their current status"
```

## Important Considerations

<Warning>
  AI-generated insights are produced by language models interpreting your Mangrove data. While powerful for exploration and analysis, always verify critical results against source data. MCP responses should complement, not replace, human judgment for compliance and reporting decisions.
</Warning>

The underlying data returned from Mangrove APIs is accurate and reflects your system of record. However, the AI assistant's interpretation and summary of that data may occasionally contain inaccuracies or miss nuanced details.