# DoiT MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) ![NPM Version](https://img.shields.io/npm/v/%40doitintl%2Fdoit-mcp-server?registry_uri=https%3A%2F%2Fregistry.npmjs.com%2F%40doitintl%2Fdoit-mcp-server)

DoiT MCP Server provides access to the DoiT API. This server enables LLMs like Claude to access DoiT platform data for troubleshooting and analysis.

![top-services](https://github.com/user-attachments/assets/749dd237-3021-439d-b447-64605393389d)

## Authentication

How you authenticate depends on the connection method:

| Method | URL / command | Auth |
| --- | --- | --- |
| Remote (Streamable HTTP) | `https://mcp.doit.com/mcp` | OAuth — your client opens a DoiT sign-in and consent page. Headless clients can instead send a customer personal API token as `Authorization: Bearer`. |
| Local (stdio) | `npx -y @doitintl/doit-mcp-server@latest` | Personal API token via `DOIT_API_KEY`. |

The legacy SSE endpoint (`https://mcp.doit.com/sse`) is deprecated and should not be used for new setups.

Your DoiT plan must include API access. Tools follow the same permissions as the [DoiT API](https://developer.doit.com/).

Tool results are capped at 140,000 serialized UTF-16 code units after response
formatting, including structured content and metadata. Oversized reads return an
actionable error; completed writes return a compact success receipt and must not
be repeated just to retrieve their output. Errors remain errors. This is a response
size policy, not a token limit or a bound on upstream downloads.

Each dispatched call emits a payload-free JSON `mcp_tool_response` event to stderr
on stdio; some clients display these logs. Hosts can supply `onResponseMetrics`
to route the events elsewhere. Use `original.serializedChars` for response-size
percentiles and `exceededLimit` for over-limit rates; `returned` measures the result
after the guard. Metrics also include UTF-8 byte counts, duration, tool/client, and
disposition, without tool arguments or response bodies.

The Claude Desktop steps below are examples, not the only supported clients. Cursor, VS Code, Amazon Q, Claude Code, and others are covered in the [Connections](https://help.doit.com/docs/mcp/connections) guide.

## Remote (Streamable HTTP)

Example with Claude Desktop: add a custom connector (**+ → Add connector → Add custom connector**) and set the remote MCP server URL to `https://mcp.doit.com/mcp`. Complete DoiT sign-in when prompted.

### Headless clients (API token)

Agents that cannot open a browser (for example HolmesGPT on a cluster, CI jobs, cron workers) can authenticate to the same endpoint with a customer [personal API token](https://help.doit.com/docs/general/profile/api-tokens) sent as a bearer header. Tools run with that token's permissions, exactly as on stdio. DoiT employee tokens are not accepted on the remote endpoint; employees use OAuth or the local server.

Example with HolmesGPT:

```yaml
mcp_servers:
  doit:
    description: "DoiT Cloud Intelligence"
    config:
      url: "https://mcp.doit.com/mcp"
      mode: streamable-http
      headers:
        Authorization: "Bearer {{ env.DOIT_API_KEY }}"
      health_check_tool: "validate_user"
```

Keep the token in a secret store and rotate it on a schedule. Design notes: [docs/remote-api-key-bearer-auth.md](docs/remote-api-key-bearer-auth.md).

## Local (stdio)

Requires Node.js v20 or higher and a personal API token as `DOIT_API_KEY`. Create a token from the [Personal API tokens](https://help.doit.com/docs/general/profile/api-tokens) page in the DoiT console.

Example with Claude Desktop — add the following to `claude_desktop_config.json` (or Settings), then [restart Claude](https://modelcontextprotocol.io/quickstart/user#3-restart-claude):

```json
{
  "mcpServers": {
    "doit_mcp_server": {
      "command": "npx",
      "args": ["-y", "@doitintl/doit-mcp-server@latest"],
      "env": {
        "DOIT_API_KEY": "your_doit_api_key"
      }
    }
  }
}
```

- `DOIT_API_KEY`: Your DoiT API token (required)
- `CUSTOMER_CONTEXT`: Customer context identifier (optional)

### Supported MCP protocol versions

The stdio server works with clients of both MCP protocol eras without any configuration:

- `2024-10-07` through `2025-11-25`, through the `initialize` handshake.
- `2026-07-28`, through `server/discover`.

Each connection's opening message decides which era it uses. See [docs/protocol-compatibility.md](docs/protocol-compatibility.md) for the details and the tests that verify it.

### Clone to Local Repository

If you want to clone and run this MCP server directly from the source code, follow these steps:

1. **Clone the repository**

```bash
git clone https://github.com/doitintl/doit-mcp-server
cd doit-mcp-server
```

2. **Install dependencies**

```bash
yarn install
```

3. **Build the project**

```bash
yarn build
```

4. **Run the server**

```bash
DOIT_API_KEY=your_doit_api_key node dist/index.js
```

## Core package API

Applications that provide their own MCP transport can reuse the published,
transport-independent implementation:

```bash
npm install @doitintl/doit-mcp-server@latest
```

```ts
import {
    COVERED_ENDPOINTS,
    executeToolHandler,
    generateTools,
    generatedToolsOpenApiSpec,
    HAND_WRITTEN_TOOLS,
} from "@doitintl/doit-mcp-server/core";
```

The `/core` entry includes the tool and prompt definitions, generated-tool
utilities, request handling, and shared configuration APIs. It does not initialize
the stdio transport or include the Cloudflare Worker, OAuth, Durable Objects, or
widget implementation.

## Usage Examples

Here are some common queries you can ask using the DoiT MCP server:

### Cost Analysis and Savings

- "What are my Flexsave savings?" - This will analyze your Flexsave cost optimization savings across your cloud accounts.
- "What are my top 3 AWS services by cost?" - This will run a Cloud Analytics query to identify your highest-spending AWS services.

### Reports and Analytics

- "List all my available reports" - This will show all Cloud Analytics reports you have access to.
- "Show me the results of my 'Monthly Cost Overview' report" - This will fetch and display results from a specific report.

### Anomaly Detection

- "What are my recent GCP anomalies?" - This will show recent cost or usage anomalies detected in your Google Cloud Platform accounts.
- "Show me details about anomaly ABC123" - This will provide detailed information about a specific anomaly.

### Invoices

- "List all my invoices" - This will show all current and historical invoices for your organization.
- "Show me details for invoice INV-2024-001" - This will provide full details for a specific invoice, including line items and payment status.

These examples demonstrate basic usage patterns. You can combine and modify these queries based on your needs. The MCP server will interpret your natural language queries and use the appropriate tools to fetch the requested information.

## Environment Variables

Used by the local stdio server. Remote `/mcp` connections authenticate with OAuth.

- `DOIT_API_KEY`: Your DoiT [personal API token](https://help.doit.com/docs/general/profile/api-tokens) (required for stdio)
- `CUSTOMER_CONTEXT`: Your customer context identifier (optional)