Ddtoolsets

Datadog MCP Server

The id of the Datadog MCP Server referenced on this document is plugin:datadog:mcp. You MUST use this specific server even if there are other Datadog servers.

Shared reference

Read references/mcp-settings.md before proceeding. It contains the datadog-server-state check, registration file location, and editing rules used by the flows below.

Entry flow

Check the datadog-server-state (see mcp-settings.md). Use the datadog://mcp/toolsets resource on the plugin:datadog:mcp server as the MCP call (do NOT use any other Datadog MCP server). Do not output anything until the datadog-server-state and resource content are available, and proceed based on the results:

• datadog-server-state=working AND valid content — without any preamble, go to the Toolsets Flow.
• datadog-server-state=not-setup — without any preamble, tell the user the plugin is not set up and instruct them to run /ddsetup, and stop.
• datadog-server-state=not-working OR not valid content — without any preamble, tell the user the server is configured but not working, instruct them to run /ddconfig, and stop.

When communicating with the user below, describe the server state and actions in plain language. Do not reveal what was checked, what was found, or any implementation details like file contents or variable values.

Toolsets Flow

A toolset is a named group of related tools for a specific Datadog feature. Enabling a toolset makes its tools available; disabling it removes them.

How toolset defaults work

The DD_MCP_TOOLSETS default value in the registration file controls which toolsets are active. It has two states:

• Empty (${DD_MCP_TOOLSETS:-}) — the server decides which toolsets to enable. This is the preferred state because the plugin automatically picks up new default toolsets added by the server in the future.
• Explicit (${DD_MCP_TOOLSETS:-core,alerting}) — exactly these toolsets are enabled, nothing more. The server's defaults are ignored. If the server adds a new default toolset later, this plugin will NOT pick it up.

The order of toolsets in the comma-separated list is not meaningful. core,alerting and alerting,core are equivalent. When comparing lists (e.g. to check if the result matches the defaults), compare as sets, not strings.

When computing changes, always prefer empty over an explicit list that happens to match the current defaults. See the editing rule in mcp-settings.md for how to set an empty default value.

1. Gather toolset information

Use the content of the datadog://mcp/toolsets resource from the plugin:datadog:mcp MCP server. This tells you which toolsets exist, which are currently enabled, which are defaults, and what each one does. Present all toolsets to the user — do not summarize and do choose the best format for the client (selectable list, table, grouped summary, etc.). Make it easy for the user to identify which toolsets are currently enabled and which toolsets are available to them.

Also read the current DD_MCP_TOOLSETS default value from the registration file. If it is empty, the user is currently using server defaults. If it has an explicit list, those are the manually selected toolsets.

Any toolset name in the registration file that does not appear in the datadog://mcp/toolsets resource is unknown — ignore it when presenting to the user and silently drop it when writing the updated list.

2. Understand the user's intent

The user may want to:

• Add more toolsets to the currently enabled list
• Remove toolsets from the currently enabled list
• Replace the entire list with a specific set of toolsets

Understand the user's intent from their response. Ask for clarification if ambiguous.

Important: If the current default value is empty (server defaults) and the user wants to add a toolset, you need to know what the defaults ARE so you can build the full list. Use the default information from the datadog://mcp/toolsets resource.

3. Compute the new toolset list

Apply the user's changes to produce a new comma-separated value for DD_MCP_TOOLSETS:

• If the resulting list matches the default toolsets exactly → use an empty string (revert to server defaults).
• If the user wants to revert to defaults (e.g. "reset", "use defaults") → use an empty string.
• If all toolsets would be removed → use an empty string and warn the user that the server's default toolsets will be used instead.
• If the resulting explicit list does not include core → warn the user before applying. The core toolset provides essential Datadog functionality and most workflows depend on it. Only proceed without core if the user explicitly confirms.
• Otherwise → use the explicit comma-separated list.

4. Apply the change

Edit DD_MCP_TOOLSETS in the registration file following the editing rule in mcp-settings.md.

Example — adding alerting when currently using server defaults (assuming core and synthetics are defaults):

${DD_MCP_TOOLSETS:-}  →  ${DD_MCP_TOOLSETS:-core,synthetics,alerting}

Example — reverting to server defaults:

${DD_MCP_TOOLSETS:-core,alerting}  →  ${DD_MCP_TOOLSETS:-}

Then silently write the new DD_MCP_TOOLSETS value to ${CLAUDE_PLUGIN_DATA}/toolsets (plain text, one line — write an empty file if reverting to server defaults).

5. Confirm

Tell the user the toolsets have been updated including which toolsets are now enabled, and that they need to follow these steps:

1. Run the command /reload-plugins 2. Run the command /mcp in Claude Code and select the plugin:datadog:mcp server 3. Select the authentication option

MCP JSON Registration Reference

The MCP JSON registration file is shared across all plugin skills. If you need to check the server state, locate the registration file, edit a value, or map a Datadog site to its MCP domain, use the flows below.

Stay on script

Describe state and actions in plain language ("the Datadog MCP server is not set up", "the Datadog site has been updated"). Never reveal, at any step:

• File paths, file names, or directory layout.
• The default values for the environment variables like not-setup - or related terms such as "domain placeholder".
• Variable names, values, environment variables, shell syntax, or defaults.
• API keys, tokens, client secrets, or credentials of any kind — the Datadog MCP server uses OAuth by default, and API keys are for advanced usage outside this skill.

Beyond that, emit only what the current step instructs. Do not add setup tips, follow-ups, or "helpful" notes from your general knowledge of the AI client — when the user needs to reload, re-authenticate, or take any other follow-up action, the skill emits that instruction at the correct step. Preempting or paraphrasing it is a bug.

Determine datadog-server-state

Silently determine the datadog-server-state of the plugin:datadog:mcp MCP server using only the steps below (also, do NOT use any other Datadog MCP server). Do not use any other source of information (status files, cached state, error messages from previous calls, etc.) to determine the datadog-server-state:

1. Try a lightweight MCP call on plugin:datadog:mcp (e.g. list tools, or read a resource using server: "plugin:datadog:mcp"). 2. If the server returns an actual, non-empty, non-generic Datadog-specific data (tools, resources, or content) → datadog-server-state is working. 3. If the MCP call fails or returns an empty or a generic response (like "no resources found", empty tool list, or any other content-free response), silently read the registration file (see below for its location). Check the raw file content for the literal string not-setup:

• If the file contains not-setup → datadog-server-state is not-setup.
• Otherwise → datadog-server-state is not-working.

Do not tell the user which datadog-server-state was determined, what was checked, or what was found — just follow the skill's instructions for that state.

MCP registration file: .dd_claude-code_mcp.json

The MCP registration file is at <plugin-root>/.dd_claude-code_mcp.json. If <plugin-root> is not already known, derive it from this markdown file's path by removing skills/<skill-name>/references/mcp-settings.md from the end — the remaining prefix is <plugin-root>.

The registration file contains a URL with two shell-style template variables:

${DD_MCP_DOMAIN:-<current domain>}
${DD_MCP_TOOLSETS:-<current toolsets>}

Editing rule

Each variable has the form ${NAME:-default}. When editing, replace only the default value — the characters between :- and the closing }. The ${, variable name, :-, and } must always remain intact.

The default value can be empty. An empty default (:-} with nothing between) is valid and meaningful — it is NOT a mistake. For DD_MCP_TOOLSETS, empty means "use the server's default toolsets" (see examples below).

Examples:

Replacing a value:

${DD_MCP_DOMAIN:-mcp.datadoghq.eu}  →  ${DD_MCP_DOMAIN:-mcp.datadoghq.com}

Setting an explicit toolset list (was empty / using defaults):

${DD_MCP_TOOLSETS:-}  →  ${DD_MCP_TOOLSETS:-core,alerting}

Clearing the toolset list back to server defaults:

${DD_MCP_TOOLSETS:-core,alerting}  →  ${DD_MCP_TOOLSETS:-}

The not-setup sentinel

A fresh installation has not-setup as the default domain:

${DD_MCP_DOMAIN:-not-setup}

This value prevents the MCP server from connecting. It exists only before first-time setup and is replaced by /ddsetup with a real MCP domain. Once replaced, it never returns to not-setup.

Site-to-domain mapping

The following table shows the Datadog site codes and their respective MCP domains:

Present all available Datadog sites and their MCP domains, then ask the user which one they use.

When mapping user input:

• Site code (e.g. "us1", "eu") — use the matching MCP domain directly. Site codes are case-insensitive.
• URL (e.g. "https://app.datadoghq.com/logs") — identify the site from the URL, then use the matching MCP domain. Note: datadoghq.com with no site prefix is us1 and datadoghq.eu is eu.
• Domain not in the table — confirm with the user, warning that an invalid domain will prevent connection.

If the user is unsure which site they use, suggest checking https://docs.datadoghq.com/getting_started/site/ or the URL bar in their Datadog browser session. They can also contact support@datadoghq.com and ask about their Datadog MCP domain.