carbonstop-agent-mcp

MCP (Model Context Protocol) server for Carbonstop Agent internal skill APIs.

This package is for server-side Agent scenarios. It wraps Carbonstop Java internal Agent APIs and forwards the Agent session identity to the gateway.

Install

npm install -g carbonstop-agent-mcp

Or run directly:

npx carbonstop-agent-mcp

Quick Start

1. Configure the Agent internal key:

export CARBONSTOP_AGENT_INTERNAL_KEY="your-agent-internal-key"

2. Start the MCP server:

npx carbonstop-agent-mcp

The npm release includes the default gateway base URL injected during the release build. For local debugging or environment override, set:

export CARBONSTOP_AGENT_BASE_URL="https://your-gateway-host"

CARBONSTOP_BASE_URL is also accepted as a compatibility fallback.

MCP Client Config

Claude Code / Claude Desktop

{
  "mcpServers": {
    "carbonstop-agent": {
      "command": "npx",
      "args": ["carbonstop-agent-mcp"],
      "env": {
        "CARBONSTOP_AGENT_INTERNAL_KEY": "your-agent-internal-key"
      }
    }
  }
}

Cursor

{
  "mcpServers": {
    "carbonstop-agent": {
      "command": "npx",
      "args": ["carbonstop-agent-mcp"],
      "env": {
        "CARBONSTOP_AGENT_INTERNAL_KEY": "your-agent-internal-key"
      }
    }
  }
}

For local debugging against a non-default gateway, add:

"CARBONSTOP_AGENT_BASE_URL": "http://localhost:8080"

Authentication

• The MCP server does not use Carbon Cloud open platform API keys.
• Each tool call must include sessionId; the Agent should pass the session id received from the server-side Agent invocation.
• The MCP server forwards:
  • X-Agent-Internal-Key: ${CARBONSTOP_AGENT_INTERNAL_KEY}
  • X-Agent-Session-Id: ${sessionId}
• The same sessionId is kept in the JSON body for audit, idempotency, trace, and business context.

Available Tools

| Tool | Description | | --- | --- | | session_context | Resolve session ownership and business context. | | project_memory_get | Read project memory. | | project_memory_patch | Patch project memory. Requires idempotencyKey. | | project_memory_compress | Save compressed project memory. Requires idempotencyKey. | | modeling_preview | Preview product carbon AI modeling. | | modeling_execute | Execute product carbon AI modeling. Requires idempotencyKey. | | modeling_update | Update an existing product carbon model. Requires accountId and idempotencyKey. | | modeling_detail | Get product carbon model details. | | report_generate | Generate a product carbon report. Requires idempotencyKey. | | report_detail | Get product carbon report detail and latest report URL. | | analysis_run | Run product carbon analysis. | | factor_search | Search and match carbon emission factors. | | knowledge_search | Search carbon knowledge. |

Tool Request Shape

Most tools forward the unified Agent skill request:

{
  "sessionId": "agent_xxx",
  "projectId": 1001,
  "accountId": 2001,
  "modelId": null,
  "reportId": null,
  "idempotencyKey": "agent_xxx_modeling_execute_v1",
  "confirmed": true,
  "pendingActionId": null,
  "input": {}
}

Write or high-risk tools require idempotencyKey, especially:

• modeling_execute
• modeling_update
• report_generate
• project_memory_patch
• project_memory_compress

API Routes

Platform APIs are called through the ai gateway prefix:

/ai/agent/internal/platform/**

Product carbon skill APIs are called through the footprint3 gateway prefix:

/footprint3/agent/internal/skills/**

Release Build

RELEASE_BASE_URL_ENCODED is a repository secret used by the GitHub Actions build to inject the default gateway base URL. It is not required in MCP client config.

Runtime environment variables still take priority:

CARBONSTOP_AGENT_BASE_URL > CARBONSTOP_BASE_URL > release build URL

License

MIT