diff --git a/content/en/bits_ai/mcp_server/_index.md b/content/en/bits_ai/mcp_server/_index.md index 4c7e070ebf1..4749f2eda58 100644 --- a/content/en/bits_ai/mcp_server/_index.md +++ b/content/en/bits_ai/mcp_server/_index.md @@ -25,10 +25,6 @@ algolia: rank: 90 --- -{{< callout url="https://www.datadoghq.com/product-preview/datadog-mcp-server/" >}} -The Datadog MCP Server is in Preview. There is no charge for using the Datadog MCP Server during the Preview, but pricing may change when the feature becomes generally available. If you're interested in the MCP server and need access, complete this form. -{{< /callout >}} - The Datadog MCP Server acts as a bridge between your observability data in Datadog and any AI agents that support the [Model Context Protocol (MCP)][1]. Providing structured access to relevant Datadog contexts, features, and tools, the MCP Server lets you query and retrieve observability insights directly from AI-powered clients such as Cursor, OpenAI Codex, Claude Code, or your own AI agent. Ready to get started? See [Set Up the Datadog MCP Server][27] for connection instructions. @@ -39,16 +35,14 @@ This demo shows the Datadog MCP Server being used in Cursor and Claude Code (unm ## Disclaimers - -- The Datadog MCP Server is not supported for production use during the Preview. -- Only Datadog organizations that have been specifically allowlisted can use the Datadog MCP Server. It is not available to the general public. - The Datadog MCP Server is HIPAA-eligible. You are responsible for ensuring that the AI tools you connect to the Datadog MCP Server meet your compliance requirements, such as HIPAA. +- The Datadog MCP Server is not GovCloud compatible. - Datadog collects certain information about your usage of the Remote Datadog MCP Server, including how you interact with it, whether errors occurred while using it, what caused those errors, and user identifiers in accordance with the Datadog Privacy Policy and Datadog's EULA. This data is used to help improve the server's performance and features, including transitions to and from the server and the applicable Datadog login page for accessing the Services, and context (for example, user prompts) leading to the use of MCP tools. The data is stored for 120 days. ## Requirements -Datadog users must have the `Incidents Read` [permission][18] to use the MCP Server. +Datadog users must have the `MCP Read`[permission][18] to use the MCP Server for read-access and `MCP Write`[permission][18] for write access. For setup instructions, see [Set Up the Datadog MCP Server](/bits_ai/mcp_server/setup). @@ -345,7 +339,7 @@ The Datadog MCP Server is under significant development. During the Preview, use [1]: https://modelcontextprotocol.io/ [15]: /api/latest/events/ [16]: /account_management/audit_trail/ -[18]: /account_management/rbac/permissions/#case-and-incident-management +[18]: /account_management/rbac/permissions/#mcp [19]: https://docs.google.com/forms/d/e/1FAIpQLSeorvIrML3F4v74Zm5IIaQ_DyCMGqquIp7hXcycnCafx4htcg/viewform [20]: /synthetics/ [21]: /continuous_integration/ diff --git a/content/en/bits_ai/mcp_server/setup.md b/content/en/bits_ai/mcp_server/setup.md index 69a10080699..3a64244e1ca 100644 --- a/content/en/bits_ai/mcp_server/setup.md +++ b/content/en/bits_ai/mcp_server/setup.md @@ -13,63 +13,37 @@ further_reading: text: "Datadog Extension for Cursor" --- -{{< callout url="https://www.datadoghq.com/product-preview/datadog-mcp-server/" >}} -The Datadog MCP Server is in Preview. There is no charge for using the Datadog MCP Server during the Preview, but pricing may change when the feature becomes generally available. If you're interested in the MCP server and need access, complete this form. -{{< /callout >}} +This page explains how to set up and configure the Datadog MCP Server, which lets you retrieve telemetry insights and manage and use platform features directly from AI-powered clients. -This page explains how to set up and configure the Datadog MCP Server, which lets you query and retrieve observability insights directly from AI-powered clients such as Cursor, OpenAI Codex, Claude Code, or your own AI agent. +Select your client to see setup instructions: -## Client compatibility - -The following AI clients are known to be compatible with the Datadog MCP Server. - -
The Datadog MCP Server is under significant development, and additional supported clients may become available.
- -| Client | Developer | Notes | -|--------|------|------| -| [Cursor][8] | Anysphere | Datadog [Cursor & VS Code extension](#connect-in-cursor-and-vs-code) recommended. | -| [Claude Code][5] | Anthropic | | -| [Claude Desktop][6] | Anthropic | Limited support for remote authentication. Use [local binary authentication](?tab=localbinaryauthentication#connect-in-supported-ai-clients) as needed. | -| [Codex CLI][7] | OpenAI | | -| [VS Code][11] | Microsoft | Datadog [Cursor & VS Code extension](#connect-in-cursor-and-vs-code) recommended. | -| [Goose][9] | Block | | -| [Kiro][22] | Amazon | | -| [Kiro CLI][10] | Amazon | | -| [Cline][17] | Cline Bot | Limited support for remote authentication. Use [local binary authentication](?tab=localbinaryauthentication#connect-in-supported-ai-clients) as needed. | - -## Connect in Cursor and VS Code +{{< tabs >}} +{{% tab "Cursor" %}} Datadog's [Cursor and VS Code extension][12] includes built-in access to the managed Datadog MCP Server. Benefits include: * No additional MCP Server setup after you install the extension and connect to Datadog. * One-click transitions between multiple Datadog organizations. -* [Cursor only] Better fixes from **Fix in Chat** on Code Insights (issues from Error Tracking, Code Vulnerabilities, and Library Vulnerabilities), informed by context from the MCP Server. +* Better fixes from **Fix in Chat** on Code Insights (issues from Error Tracking, Code Vulnerabilities, and Library Vulnerabilities), informed by context from the MCP Server. To install the extension: -1. If you previously installed the Datadog MCP Server manually, remove it from the IDE's configuration to avoid conflicts. To find the MCP Server configuration: - - Cursor: Go to **Cursor Settings** (`Shift` + `Cmd/Ctrl` + `J`) and select the **MCP** tab. - - VS Code: Open the command palette (`Shift` + `Cmd/Ctrl` + `P`) and run `MCP: Open User Configuration`. +1. If you previously installed the Datadog MCP Server manually, remove it from the IDE's configuration to avoid conflicts. Go to **Cursor Settings** (`Shift` + `Cmd/Ctrl` + `J`) and select the **MCP** tab. 2. Install the Datadog extension following [these instructions][14]. If you have the extension installed already, make sure it's the latest version, as new features are released regularly. 3. Sign in to your Datadog account. If you have multiple accounts, use the account included in your Product Preview. - {{< img src="bits_ai/mcp_server/ide_sign_in.png" alt="Sign in to Datadog from the IDE extension" style="width:70%;" >}} + {{< img src="bits_ai/mcp_server/ide_sign_in.png" alt="Sign in to Datadog from the IDE extension" style="width:70%;" >}} 4. **Restart the IDE.** -5. Confirm the Datadog MCP Server is available and the [tools][20] are listed in your IDE: - - Cursor: Go to **Cursor Settings** (`Shift` + `Cmd/Ctrl` + `J`), and select the **MCP** tab. - - VS Code: Open the chat panel, select agent mode, and click the **Configure Tools** button. - {{< img src="bits_ai/mcp_server/vscode_configure_tools_button.png" alt="Configure Tools button in VS Code" style="width:70%;" >}} +5. Confirm the Datadog MCP Server is available and the [tools][20] are listed: Go to **Cursor Settings** (`Shift` + `Cmd/Ctrl` + `J`), and select the **MCP** tab. -## Connect in other AI clients +{{% /tab %}} -The following instructions are for all [MCP-compatible clients][21]. For Cursor or VS Code, use the [Datadog extension](#connect-in-cursor-and-vs-code) for built-in access to the Datadog MCP Server. +{{% tab "Claude Code" %}} -{{< tabs >}} -{{% tab "Remote authentication" %}} -This method uses the MCP specification's [Streamable HTTP][1] transport mechanism to connect to the MCP Server. +You can connect Claude Code to the Datadog MCP Server using remote authentication (HTTP) or local binary authentication (stdio). -Point your AI agent to the MCP Server endpoint for your regional [Datadog site][2]. For example, if you're using `app.datadoghq.com` to access Datadog, use the endpoint for the US1 site. +**Remote authentication** -If your organization uses a [custom sub-domain][3], use the endpoint that corresponds to your regional Datadog site. For example, if your custom sub-domain is `myorg.datadoghq.com`, use the US1 endpoint. +Point your AI agent to the MCP Server endpoint for your regional [Datadog site](/getting_started/site/). For example, if you're using `app.datadoghq.com`, use the US1 endpoint. | Datadog Site | MCP Server Endpoint | |--------|------| @@ -80,20 +54,12 @@ If your organization uses a [custom sub-domain][3], use the endpoint that corres | **AP1** (`ap1.datadoghq.com`) | `https://mcp.ap1.datadoghq.com/api/unstable/mcp-server/mcp` | | **AP2** (`ap2.datadoghq.com`) | `https://mcp.ap2.datadoghq.com/api/unstable/mcp-server/mcp` | -### Example configurations - -These examples are for the US1 site: - -* **Command line**: For Claude Code, run: +* **Command line**: Run (use the endpoint for your site from the table above): ```bash claude mcp add --transport http datadog-mcp https://mcp.datadoghq.com/api/unstable/mcp-server/mcp ``` -* **Configuration file**: Edit the configuration file for your AI agent: - * Codex CLI: `~/.codex/config.toml` - * Gemini CLI: `~/.gemini/settings.json` - * Kiro CLI: `~/.kiro/settings/mcp.json` - +* **Configuration file**: Add to `~/.claude.json`: ```json { "mcpServers": { @@ -105,62 +71,184 @@ These examples are for the US1 site: } ``` -[1]: https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http -[2]: /getting_started/site/ -[3]: /account_management/multi_organization/#custom-sub-domains +**Local binary authentication** + +Use this option if remote authentication is not available. After installation, you typically do not need to update the local binary to benefit from MCP Server updates, as the tools are remote. + +1. Install the Datadog MCP Server binary (macOS and Linux): + ```bash + curl -sSL https://coterm.datadoghq.com/mcp-cli/install.sh | bash + ``` + This installs the binary to `~/.local/bin/datadog_mcp_cli`. + +2. Run `datadog_mcp_cli login` manually to walk through the OAuth login flow and choose a [Datadog site](/getting_started/site/). + +3. Configure Claude Code. Add to `~/.claude.json` (replace `` with your username): + ```json + { + "mcpServers": { + "datadog": { + "type": "stdio", + "command": "/Users//.local/bin/datadog_mcp_cli", + "args": [], + "env": {} + } + } + } + ``` + Or run: `claude mcp add datadog --scope user -- ~/.local/bin/datadog_mcp_cli` + {{% /tab %}} -{{% tab "Local binary authentication" %}} +{{% tab "Claude Desktop" %}} + +Claude Desktop has limited support for remote authentication. Use **local binary authentication** for reliable setup. + +1. Install the Datadog MCP Server binary (macOS and Linux): + ```bash + curl -sSL https://coterm.datadoghq.com/mcp-cli/install.sh | bash + ``` + This installs the binary to `~/.local/bin/datadog_mcp_cli`. + Windows: Download the [Windows version](https://coterm.datadoghq.com/mcp-cli/datadog_mcp_cli.exe). + +2. Run `datadog_mcp_cli login` manually to walk through the OAuth login flow and choose a [Datadog site](/getting_started/site/). + +3. Configure Claude Desktop to use the Datadog MCP Server. Add to your Claude Desktop configuration (location varies by OS) with the `stdio` transport pointing to `datadog_mcp_cli`: + ```json + { + "mcpServers": { + "datadog": { + "type": "stdio", + "command": "/Users//.local/bin/datadog_mcp_cli", + "args": [], + "env": {} + } + } + } + ``` -This method uses the MCP specification's [stdio][1] transport mechanism to connect to the MCP Server. +{{% /tab %}} -Use this option if direct remote authentication is not available for you. After installation, you typically do not need to update the local binary to benefit from MCP Server updates, as the tools are remote. +{{% tab "Codex" %}} -1. Install the Datadog MCP Server binary: - * macOS and Linux: - ```bash - curl -sSL https://coterm.datadoghq.com/mcp-cli/install.sh | bash - ``` +Point your AI agent to the MCP Server endpoint for your regional [Datadog site](/getting_started/site/). For example, for US1 use `https://mcp.datadoghq.com/api/unstable/mcp-server/mcp`. See the endpoint table in the [Claude Code](#claude-code) tab for all sites. - This installs the MCP Server binary to `~/.local/bin/datadog_mcp_cli` and then you can use it like any other stdio MCP server.

+Edit `~/.codex/config.toml` (or your Codex CLI configuration file) to add the Datadog MCP Server with HTTP transport and the endpoint URL for your site. - * Windows: Download the [Windows version][2]. +Example JSON-style configuration (US1): -2. Run `datadog_mcp_cli login` manually to walk through the OAuth login flow. +```json +{ + "mcpServers": { + "datadog": { + "type": "http", + "url": "https://mcp.datadoghq.com/api/unstable/mcp-server/mcp" + } + } +} +``` - The MCP Server automatically starts the OAuth flow if a client needs it, but doing it manually lets you choose a [Datadog site][3] and avoid the AI client timing out. +{{% /tab %}} -3. Configure your AI client to use the Datadog MCP Server. Follow your client's configuration instructions, as MCP Server setup varies between third-party AI clients. +{{% tab "VS Code" %}} - For example, for Claude Code, add this to `~/.claude.json`, making sure to replace `` in the command path: +Datadog's [Cursor and VS Code extension][12] includes built-in access to the managed Datadog MCP Server. Benefits include: - ```json - { - "mcpServers": { - "datadog": { - "type": "stdio", - "command": "/Users//.local/bin/datadog_mcp_cli", - "args": [], - "env": {} - } - } - } - ``` +* No additional MCP Server setup after you install the extension and connect to Datadog. +* One-click transitions between multiple Datadog organizations. + +To install the extension: - Alternatively, you can also configure Claude Code by running the following: - ```bash - claude mcp add datadog --scope user -- ~/.local/bin/datadog_mcp_cli - ``` +1. If you previously installed the Datadog MCP Server manually, remove it from the IDE's configuration to avoid conflicts. Open the command palette (`Shift` + `Cmd/Ctrl` + `P`) and run `MCP: Open User Configuration`. +2. Install the Datadog extension following [these instructions][14]. If you have the extension installed already, make sure it's the latest version. +3. Sign in to your Datadog account. If you have multiple accounts, use the account included in your Product Preview. +4. **Restart the IDE.** +5. Confirm the Datadog MCP Server is available and the [tools][20] are listed: Open the chat panel, select agent mode, and click the **Configure Tools** button. + {{< img src="bits_ai/mcp_server/vscode_configure_tools_button.png" alt="Configure Tools button in VS Code" style="width:70%;" >}} + +{{% /tab %}} + +{{% tab "Other" %}} + +The following clients can connect to the Datadog MCP Server: [Goose](https://github.com/block/goose), [Kiro](https://kiro.dev/), [Kiro CLI](https://kiro.dev/cli/), [Cline](https://cline.bot/), and other MCP-compatible clients. Use **remote authentication** when your client supports it. For Cline (and when remote auth is unreliable), use **local binary authentication**. + +**Remote authentication** + +Point your AI agent to the MCP Server endpoint for your regional [Datadog site](/getting_started/site/): + +| Datadog Site | MCP Server Endpoint | +|--------|------| +| **US1** (`app.datadoghq.com`) | `https://mcp.datadoghq.com/api/unstable/mcp-server/mcp` | +| **US3** (`us3.datadoghq.com`) | `https://mcp.us3.datadoghq.com/api/unstable/mcp-server/mcp` | +| **US5** (`us5.datadoghq.com`) | `https://mcp.us5.datadoghq.com/api/unstable/mcp-server/mcp` | +| **EU1** (`app.datadoghq.eu`) | `https://mcp.datadoghq.eu/api/unstable/mcp-server/mcp` | +| **AP1** (`ap1.datadoghq.com`) | `https://mcp.ap1.datadoghq.com/api/unstable/mcp-server/mcp` | +| **AP2** (`ap2.datadoghq.com`) | `https://mcp.ap2.datadoghq.com/api/unstable/mcp-server/mcp` | + +Add the Datadog MCP Server to your client's configuration using the HTTP transport and the endpoint above. Example config file locations: + +| Client | Configuration file | +|--------|---------------------| +| Gemini CLI | `~/.gemini/settings.json` | +| Kiro CLI | `~/.kiro/settings/mcp.json` | + +Example JSON configuration (US1): + +```json +{ + "mcpServers": { + "datadog": { + "type": "http", + "url": "https://mcp.datadoghq.com/api/unstable/mcp-server/mcp" + } + } +} +``` + +**Local binary authentication** (recommended for Cline and when remote auth is unreliable) + +1. Install the Datadog MCP Server binary (macOS and Linux): + ```bash + curl -sSL https://coterm.datadoghq.com/mcp-cli/install.sh | bash + ``` + This installs the binary to `~/.local/bin/datadog_mcp_cli`. + Windows: Download the [Windows version](https://coterm.datadoghq.com/mcp-cli/datadog_mcp_cli.exe). + +2. Run `datadog_mcp_cli login` manually to walk through the OAuth login flow and choose a [Datadog site](/getting_started/site/). + +3. Configure your AI client to use the stdio transport with `datadog_mcp_cli` as the command. Example: + ```json + { + "mcpServers": { + "datadog": { + "type": "stdio", + "command": "/Users//.local/bin/datadog_mcp_cli", + "args": [], + "env": {} + } + } + } + ``` -[1]: https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#stdio -[2]: https://coterm.datadoghq.com/mcp-cli/datadog_mcp_cli.exe -[3]: /getting_started/site/ {{% /tab %}} {{< /tabs >}} +### Supported clients + +| Client | Developer | Notes | +|--------|------|------| +| [Cursor][8] | Cursor | Datadog [Cursor & VS Code extension](#cursor) recommended. | +| [Claude Code][5] | Anthropic | | +| [Claude Desktop][6] | Anthropic | Limited support for remote authentication. Use [local binary authentication](#claude-desktop) as needed. | +| [Codex CLI][7] | OpenAI | | +| [VS Code][11] | Microsoft | Datadog [Cursor & VS Code extension](#vs-code) recommended. | +| [Goose](https://github.com/block/goose), [Kiro](https://kiro.dev/), [Kiro CLI](https://kiro.dev/cli/), [Cline](https://cline.bot/) | Various | See the **Other** tab above. Use local binary authentication for Cline if remote auth is unreliable. | + +
The Datadog MCP Server is under significant development, and additional supported clients may become available.
+ ### Authentication -The MCP Server uses OAuth 2.0 for [authentication][2]. If you cannot go through the OAuth flow (for example, on a server), you can provide a Datadog [API key and application key][3] as `DD_API_KEY` and `DD_APPLICATION_KEY` HTTP headers. For example: +The MCP Server uses OAuth 2.0 for [authentication][auth]. If you cannot go through the OAuth flow (for example, on a server), you can provide a Datadog [API key and application key][3] as `DD_API_KEY` and `DD_APPLICATION_KEY` HTTP headers. For example: {{< code-block lang="json" >}} { @@ -182,21 +270,22 @@ For security, use a scoped API key and application key from a [service account][ ### Test access to the MCP Server 1. Install the [MCP inspector][4], a developer tool for testing and debugging MCP servers. - - ```bash - npx @modelcontextprotocol/inspector - ``` + ```bash + npx @modelcontextprotocol/inspector + ``` 2. In the inspector's web UI, for **Transport Type**, select **Streamable HTTP**. -3. For **URL**, enter the [MCP Server URL](?tab=remoteauthentication#connect-in-supported-ai-clients) for your regional Datadog site. +3. For **URL**, enter the MCP Server endpoint for your regional Datadog site (for example, for US1: `https://mcp.datadoghq.com/api/unstable/mcp-server/mcp`). See the endpoint table in the tabs above for other sites. 4. Click **Connect**, then go to **Tools** > **List Tools**. 5. Check if the [available tools][20] appear. - ## Further reading {{< partial name="whats-next/whats-next.html" >}} -[2]: https://modelcontextprotocol.io/specification/draft/basic/authorization +[site]: /getting_started/site/ +[auth]: https://modelcontextprotocol.io/specification/draft/basic/authorization +[win]: https://coterm.datadoghq.com/mcp-cli/datadog_mcp_cli.exe +[win-other]: https://coterm.datadoghq.com/mcp-cli/datadog_mcp_cli.exe [3]: /account_management/api-app-keys/ [4]: https://github.com/modelcontextprotocol/inspector [5]: https://www.anthropic.com/claude-code