From 2069633a8b8b3e8bb4f488a53828a4078fc9504d Mon Sep 17 00:00:00 2001 From: Amy Zhou Date: Tue, 15 Sep 2026 16:24:57 -0400 Subject: [PATCH 1/2] [DOCS-15663] Add Code Execution page for the Datadog MCP Server Add a dedicated page explaining the code-exec toolset's value and how to enable it, and cross-link it from the MCP Server setup, tools, and overview pages. --- hugo/config/_default/menus/main.en.yaml | 5 ++ hugo/content/en/mcp_server/_index.md | 3 + hugo/content/en/mcp_server/code_execution.md | 76 ++++++++++++++++++++ hugo/content/en/mcp_server/setup.md | 8 ++- hugo/content/en/mcp_server/tools.md | 6 +- 5 files changed, 95 insertions(+), 3 deletions(-) create mode 100644 hugo/content/en/mcp_server/code_execution.md diff --git a/hugo/config/_default/menus/main.en.yaml b/hugo/config/_default/menus/main.en.yaml index 740970f86bd..020b50066f4 100644 --- a/hugo/config/_default/menus/main.en.yaml +++ b/hugo/config/_default/menus/main.en.yaml @@ -1278,6 +1278,11 @@ menu: identifier: mcp_server_tools parent: mcp_server weight: 2 + - name: Code Execution + url: mcp_server/code_execution + identifier: mcp_server_code_execution + parent: mcp_server + weight: 3 - name: Partners url: partners/ pre: colab diff --git a/hugo/content/en/mcp_server/_index.md b/hugo/content/en/mcp_server/_index.md index 4245466a006..a7402873ed4 100644 --- a/hugo/content/en/mcp_server/_index.md +++ b/hugo/content/en/mcp_server/_index.md @@ -13,6 +13,9 @@ further_reading: - link: "mcp_server/tools" tag: "Documentation" text: "Datadog MCP Server Tools" +- link: "mcp_server/code_execution" + tag: "Documentation" + text: "Code Execution" - link: "bits_ai/" tag: "Documentation" text: "Bits AI Overview" diff --git a/hugo/content/en/mcp_server/code_execution.md b/hugo/content/en/mcp_server/code_execution.md new file mode 100644 index 00000000000..a322fe2a675 --- /dev/null +++ b/hugo/content/en/mcp_server/code_execution.md @@ -0,0 +1,76 @@ +--- +title: Code Execution +description: "Run agent-authored TypeScript against Datadog APIs in a single MCP tool call to investigate issues that span multiple Datadog products." +algolia: + tags: ["mcp", "mcp server", "code execution", "code-exec"] + rank: 65 +further_reading: +- link: "mcp_server" + tag: "Documentation" + text: "Datadog MCP Server" +- link: "mcp_server/setup" + tag: "Documentation" + text: "Set Up the Datadog MCP Server" +- link: "mcp_server/tools" + tag: "Documentation" + text: "Datadog MCP Server Tools" +--- + +## Overview + +The `code-exec` toolset lets your AI agent write and run TypeScript against Datadog APIs in a single MCP tool call, instead of one tool call per API request. The agent's generated code runs inside a Datadog-managed sandbox. Only the value the code returns is sent back to the agent. This keeps large API responses out of the model's context. + +Use code execution for investigations that span multiple Datadog products, or that need the agent to join, filter, or summarize data from several calls. An example is correlating error logs with APM latency for the same service and time window. + +## Why use code execution + +Without code execution, an agent that wants to enrich the top error-generating services with APM latency data needs a separate tool call for each service. It also needs additional turns to combine the results. Each of those calls and turns consumes context window space. + +With code execution, the agent expresses the same investigation as a single script: + +1. Query logs for the services with the most error logs in a time window. +1. For each returned service, query spans for latency data. +1. Join the two result sets and return a compact object. + +The MCP Server runs the script and returns only the joined result. The agent completes the investigation in one tool call instead of one call per service. + +## Available tools + +The `code-exec` toolset provides: + +- **`execute_code`**: Runs agent-authored TypeScript in the sandbox and returns a structured result. See [`execute_code`][1] in the MCP Server Tools reference for permissions and example prompts. +- **`search_datadog_sdk`**: Looks up the SDK functions and API methods available to the agent for writing scripts. + +Generated code is based on the public [Datadog API Client for TypeScript][2]. + +## What the sandbox can access + +Code executed by the `code-exec` toolset runs against Datadog APIs using your own user identity. An agent can only read data that you already have access to: + +- The sandbox is isolated. Scripts can't access your local machine, file system, arbitrary network destinations, or raw Datadog credentials. +- The sandbox only exposes read-only Datadog API calls. An agent can't use `execute_code` to perform write actions, such as creating a monitor or updating a dashboard. +- API calls made from a script apply your existing [role permissions][3]. If you don't have access to a dataset, the agent can't query it through `execute_code` either. +- Raw API responses stay inside the sandbox while the script processes them. Only the value the script returns is sent to the agent. Review what a script returns if the underlying data is sensitive, such as customer data stored in logs. + +## Enable code execution + +To enable code execution, include `code-exec` in the `toolsets` query parameter when you connect your AI client to the Datadog MCP Server. See [Set Up the Datadog MCP Server][4] for client-specific connection instructions. + +{{< site-region region="us,us3,us5,eu,ap1,ap2,uk1" >}} +For example, based on your selected [Datadog site][5] ({{< region-param key="dd_site_name" >}}), this URL enables the core toolset alongside code execution: + +
{{< region-param key="mcp_server_endpoint" >}}?toolsets=core,code-exec
+ +`code-exec` is included in `toolsets=all`, so you don't need to add it separately if you already enable all generally available toolsets. + +[5]: /getting_started/site/ +{{< /site-region >}} + +## Further reading + +{{< partial name="whats-next/whats-next.html" >}} + +[1]: /mcp_server/tools/#execute_code +[2]: https://github.com/DataDog/datadog-api-client-typescript +[3]: /account_management/rbac/permissions/ +[4]: /mcp_server/setup diff --git a/hugo/content/en/mcp_server/setup.md b/hugo/content/en/mcp_server/setup.md index 3ccfe38eb79..c08748834b3 100644 --- a/hugo/content/en/mcp_server/setup.md +++ b/hugo/content/en/mcp_server/setup.md @@ -13,6 +13,9 @@ further_reading: - link: "mcp_server/tools" tag: "Documentation" text: "Datadog MCP Server Tools" +- link: "mcp_server/code_execution" + tag: "Documentation" + text: "Code Execution" - link: "https://www.datadoghq.com/blog/kubernetes-mcp-tools/" tag: "Blog" text: "Investigate Kubernetes resources with Datadog MCP tools" @@ -710,7 +713,7 @@ These toolsets are generally available. See [Datadog MCP Server Tools][49] for a - `core`: The default toolset for logs, metrics, traces, dashboards, monitors, incidents, hosts, services, events, and notebooks - `alerting`: Tools for validating and creating monitors, searching monitor groups, retrieving monitor templates, analyzing monitor coverage, and searching SLOs - `audit-trail`: Tools for [Audit Trail][70], including searching and retrieving Audit Trail events and forming Audit Trail search queries -- `code-exec`: A single tool that runs agent-authored TypeScript in a Datadog-managed sandbox with direct access to Datadog APIs, for multi-signal investigation and ad-hoc data exploration in one call +- `code-exec`: A single tool that runs agent-authored TypeScript in a Datadog-managed sandbox with direct access to Datadog APIs, for multi-signal investigation and ad-hoc data exploration in one call. See [Code Execution][73] for more information. - `cost`: Tools for [Cloud Cost Management][63], including listing cost-saving recommendations ranked by estimated potential daily savings - `dashboards`: Tools for retrieving, creating, updating, and deleting [dashboards][46], plus widget schema reference and validation - `data-observability`: Tools for [Data Observability][69], including data catalog search, lineage analysis, data quality monitoring, and cost and performance recommendations for data warehouses and Spark jobs @@ -996,4 +999,5 @@ Local authentication is recommended for Cline and when remote authentication is [69]: /data_observability/ [70]: /account_management/audit_trail/ [71]: https://x.ai/build -[72]: https://github.com/xai-org/plugin-marketplace +[72]: https://github.com/xai-org/plugin-marketplace +[73]: /mcp_server/code_execution/ diff --git a/hugo/content/en/mcp_server/tools.md b/hugo/content/en/mcp_server/tools.md index 7a98c1ac414..42656fdf52b 100644 --- a/hugo/content/en/mcp_server/tools.md +++ b/hugo/content/en/mcp_server/tools.md @@ -13,6 +13,9 @@ further_reading: - link: "mcp_server/setup" tag: "Documentation" text: "Set Up the Datadog MCP Server" +- link: "mcp_server/code_execution" + tag: "Documentation" + text: "Code Execution" - link: "https://www.datadoghq.com/blog/datadog-mcp-apps/" tag: "Blog" text: "Datadog MCP Apps: Interactive experiences in AI workflows" @@ -500,7 +503,7 @@ Lists an organization's Cloud Cost Management cost-saving recommendations, ranke ## Code Execution -A single tool that runs agent-authored TypeScript in a Datadog-managed sandbox with direct access to Datadog APIs, for multi-signal investigation and ad-hoc data exploration in one call. +A single tool that runs agent-authored TypeScript in a Datadog-managed sandbox with direct access to Datadog APIs, for multi-signal investigation and ad-hoc data exploration in one call. See [Code Execution][74] for more information on how this toolset works and when to use it. Code executed by this toolset runs against your Datadog APIs using your own user identity. The sandbox applies your existing [role permissions][56] to every API call, so an agent can only read or modify data that you can already access in Datadog. @@ -2511,6 +2514,7 @@ Cancels a running workflow execution instance. Invoke this tool only when the us [71]: /account_management/audit_trail/ [72]: /actions/forms/ [73]: /real_user_monitoring/operations_monitoring/ +[74]: /mcp_server/code_execution/ ## Further reading From c36d2fcdebf792d0ee4603568f2af4bf99a385f3 Mon Sep 17 00:00:00 2001 From: Amy Zhou Date: Tue, 15 Sep 2026 16:55:29 -0400 Subject: [PATCH 2/2] Use JavaScript for code-exec language, document search_datadog_sdk Corrects the language the code-exec toolset writes from TypeScript to JavaScript on the new Code Execution page, and adds the missing search_datadog_sdk tool entry to the MCP Server Tools reference. --- hugo/content/en/mcp_server/code_execution.md | 25 ++++++++++---------- hugo/content/en/mcp_server/tools.md | 9 +++++++ 2 files changed, 22 insertions(+), 12 deletions(-) diff --git a/hugo/content/en/mcp_server/code_execution.md b/hugo/content/en/mcp_server/code_execution.md index a322fe2a675..3ed36346d92 100644 --- a/hugo/content/en/mcp_server/code_execution.md +++ b/hugo/content/en/mcp_server/code_execution.md @@ -1,6 +1,6 @@ --- title: Code Execution -description: "Run agent-authored TypeScript against Datadog APIs in a single MCP tool call to investigate issues that span multiple Datadog products." +description: "Run agent-authored JavaScript against Datadog APIs in a single MCP tool call to investigate issues that span multiple Datadog products." algolia: tags: ["mcp", "mcp server", "code execution", "code-exec"] rank: 65 @@ -18,7 +18,7 @@ further_reading: ## Overview -The `code-exec` toolset lets your AI agent write and run TypeScript against Datadog APIs in a single MCP tool call, instead of one tool call per API request. The agent's generated code runs inside a Datadog-managed sandbox. Only the value the code returns is sent back to the agent. This keeps large API responses out of the model's context. +The `code-exec` toolset lets your AI agent write and run JavaScript against Datadog APIs in a single MCP tool call, instead of one tool call per API request. The agent's generated code runs inside a Datadog-managed sandbox. Only the value the code returns is sent back to the agent. This keeps large API responses out of the model's context. Use code execution for investigations that span multiple Datadog products, or that need the agent to join, filter, or summarize data from several calls. An example is correlating error logs with APM latency for the same service and time window. @@ -38,10 +38,10 @@ The MCP Server runs the script and returns only the joined result. The agent com The `code-exec` toolset provides: -- **`execute_code`**: Runs agent-authored TypeScript in the sandbox and returns a structured result. See [`execute_code`][1] in the MCP Server Tools reference for permissions and example prompts. -- **`search_datadog_sdk`**: Looks up the SDK functions and API methods available to the agent for writing scripts. +- **`execute_code`**: Runs agent-authored JavaScript in the sandbox and returns a structured result. See [`execute_code`][1] in the MCP Server Tools reference for permissions and example prompts. +- **`search_datadog_sdk`**: Looks up the SDK functions and API methods available to the agent for writing scripts. See [`search_datadog_sdk`][2] in the MCP Server Tools reference. -Generated code is based on the public [Datadog API Client for TypeScript][2]. +Generated code is JavaScript based on the public [Datadog API Client for TypeScript][3]. ## What the sandbox can access @@ -49,21 +49,21 @@ Code executed by the `code-exec` toolset runs against Datadog APIs using your ow - The sandbox is isolated. Scripts can't access your local machine, file system, arbitrary network destinations, or raw Datadog credentials. - The sandbox only exposes read-only Datadog API calls. An agent can't use `execute_code` to perform write actions, such as creating a monitor or updating a dashboard. -- API calls made from a script apply your existing [role permissions][3]. If you don't have access to a dataset, the agent can't query it through `execute_code` either. +- API calls made from a script apply your existing [role permissions][4]. If you don't have access to a dataset, the agent can't query it through `execute_code` either. - Raw API responses stay inside the sandbox while the script processes them. Only the value the script returns is sent to the agent. Review what a script returns if the underlying data is sensitive, such as customer data stored in logs. ## Enable code execution -To enable code execution, include `code-exec` in the `toolsets` query parameter when you connect your AI client to the Datadog MCP Server. See [Set Up the Datadog MCP Server][4] for client-specific connection instructions. +To enable code execution, include `code-exec` in the `toolsets` query parameter when you connect your AI client to the Datadog MCP Server. See [Set Up the Datadog MCP Server][5] for client-specific connection instructions. {{< site-region region="us,us3,us5,eu,ap1,ap2,uk1" >}} -For example, based on your selected [Datadog site][5] ({{< region-param key="dd_site_name" >}}), this URL enables the core toolset alongside code execution: +For example, based on your selected [Datadog site][6] ({{< region-param key="dd_site_name" >}}), this URL enables the core toolset alongside code execution: 
{{< region-param key="mcp_server_endpoint" >}}?toolsets=core,code-exec
`code-exec` is included in `toolsets=all`, so you don't need to add it separately if you already enable all generally available toolsets. -[5]: /getting_started/site/ +[6]: /getting_started/site/ {{< /site-region >}} ## Further reading @@ -71,6 +71,7 @@ For example, based on your selected [Datadog site][5] ({{< region-param key="dd_ {{< partial name="whats-next/whats-next.html" >}} [1]: /mcp_server/tools/#execute_code -[2]: https://github.com/DataDog/datadog-api-client-typescript -[3]: /account_management/rbac/permissions/ -[4]: /mcp_server/setup +[2]: /mcp_server/tools/#search_datadog_sdk +[3]: https://github.com/DataDog/datadog-api-client-typescript +[4]: /account_management/rbac/permissions/ +[5]: /mcp_server/setup diff --git a/hugo/content/en/mcp_server/tools.md b/hugo/content/en/mcp_server/tools.md index 42656fdf52b..5f4c724a4bf 100644 --- a/hugo/content/en/mcp_server/tools.md +++ b/hugo/content/en/mcp_server/tools.md @@ -516,6 +516,15 @@ Executes AI agent-authored TypeScript in a Datadog-managed sandbox. The code rec - Compare error-span counts, monitor alerts, and config changes for the `payments` service over the last day, and identify anything that moved at the same time. - For `auth-service`, correlate the top error patterns in logs with CPU and memory metrics from the last hour to see whether errors track resource pressure. +### `search_datadog_sdk` +*Toolset: **code-exec***\ +*Permissions Required: None*\ +Looks up the SDK functions, types, and API methods available for writing `execute_code` scripts. Call this before writing a script to confirm which methods exist and their signatures. + +- What SDK methods are available for querying logs in a script? +- Show me the available methods for aggregating spans. +- What does the `dd.time` namespace provide? + ## Dashboards Tools for retrieving, creating, updating, and deleting [dashboards][46], plus widget schema reference and validation.