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

Authentication

How you authenticate depends on the connection method:

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.

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 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 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:

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.

Local (stdio)

Supports Skills over MCP for compatible clients. No skills are bundled by default.

Requires Node.js v20 or higher and a personal API token as DOIT_API_KEY. Create a token from the Personal API tokens page in the DoiT console.

Example with Claude Desktop — add the following to claude_desktop_config.json (or Settings), then restart Claude:

{
  "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 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

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

2. Install dependencies

yarn install

3. Build the project

yarn build

4. Run the server

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:

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

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.

Large results

Claude accepts about 150,000 characters per tool result, so executeToolHandler caps every result at 140,000 characters. A list result that would exceed the cap is returned in parts instead of failing: the server keeps the records that fit, adds pageSplit: { returnedRecords, remainingInResult }, and sets pageToken to a signed continuation token. Passing that token back to the same tool returns the next part; the API's own cursor appears only once the whole API page has been delivered, so no record is skipped or repeated. If the record a part stopped at is deleted before the next call, the continuation resumes at its index, so a record is repeated rather than skipped. Paging is opt-in: a read-only list tool whose endpoint has no paging of its own declares resultPaged: true (hand-written tools on the tool object, generated ones in src/tools/generated/overrides.ts) and gains an optional pageToken argument. Single-resource tools have nothing to split, and reads that must not be re-run (ask_ava_sync) stay out. Analytics results (rows) are never split and keep the size error with a narrowing hint. Fields other than the record collection (counts, sibling maps such as a components statussheet) describe the whole result and repeat on every part. Consumers that register the generated registry's schemas advertise the argument on opted-in generated tools and should pass resultPaging so it takes effect.

The stdio server signs tokens with a random per-process secret. A consumer that provides its own transport passes resultPaging: { secret, cursorField } to executeToolHandler, and applies withResultPageToken to the zod schema of every tool in RESULT_PAGED_TOOLS when it registers tools from the exported schemas, so both transports advertise the same arguments.

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.

Claude Code plugin and channel (research preview)

A Claude Code plugin in this repository pushes new cost anomalies and cloud incidents into an open session. It sends events only; the tools come from the DoiT Cloud Intelligence plugin or the remote connector.

/plugin install doit --marketplace doitintl/doit-mcp-server

See docs/channels.md for how to start Claude Code with the channel and what an organization needs to allow.

Environment Variables

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

• DOIT_API_KEY: Your DoiT personal API token (required for stdio)
• CUSTOMER_CONTEXT: Your customer context identifier (optional)
• DOIT_CHANNEL_EVENTS: Opt in to Claude Code channel mode (research preview) by listing event kinds to push into an open session: anomalies, incidents (optional, off by default)
• DOIT_CHANNEL_POLL_SECONDS: Channel poll interval in seconds, minimum 60 (optional, default 300)
• DOIT_CHANNEL_ONLY: Set to true to serve channel events and no tools, for a session that has the DoiT tools from another connection (optional)