Ddconfig

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, editing rules, and site-to-domain mapping used by the flows below.

Entry flow

Check the datadog-server-state (see mcp-settings.md). Use the datadog://mcp/whoami 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, immediately show the user their current connection (from whoami): user name and email, organization name, and site (the dd_site value). Then let the user choose between using a different Datadog MCP domain or site or switching to a different Datadog organization.
• 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 and go to the Troubleshooting Flow.

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.

Troubleshooting Flow

The server is configured but not responding. Read the current domain from the registration file (see mcp-settings.md for the file format and how to find the domain), then present the user with the likely causes — do not follow these sequentially, show them all and use judgment:

• Domain issue. Compare the domain against the site-to-domain table in mcp-settings.md. Only flag it as suspicious if it looks like a typo or a clearly malformed URL (e.g. mcp.us5.datadog.com missing the hq). A domain not in the standard table is not necessarily wrong — the user may be using a valid non-standard domain.
• Authentication. The authentication may have expired or was never completed, and the user needs to follow these steps:

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

• Network or access. The user's network may be blocking the connection, or their Datadog account may not have API access, like not having the MCP Read permission.

If the domain looks wrong, suggest running the Domain Flow to correct it.

Domain Flow

Changes the Datadog MCP domain the server connects to.

1. Show the current domain information (from whoami → dd_site if available, or from the current domain in the registration file — see mcp-settings.md for the file format). Present it in plain language (e.g. "the plugin is currently connected to …") — follow the "Stay on script" rule in mcp-settings.md. 2. Ask for the new domain. Present the available sites and their MCP domains from mcp-settings.md, and ask which domain to switch to. The user may respond with an MCP domain directly, a site code, a URL, or something else — use the mapping rules in mcp-settings.md to resolve the answer. Ask for clarification if ambiguous.

Follow the "Stay on script" rule in mcp-settings.md. In particular, do not preview the follow-up instructions from step 4 below (reload, re-authenticate, etc.) — that step emits them verbatim at the right moment.

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

Before (example):

   ${DD_MCP_DOMAIN:-mcp.datadoghq.eu}

After (switching to us1):

   ${DD_MCP_DOMAIN:-mcp.datadoghq.com}

4. Tell the user the domain has been changed and 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

Organization Flow

Switches to a different Datadog organization. The agent cannot do this automatically — the user must select the target organization in the browser.

Ask the user if they want to use an organization on the same domain or on a different domain.

• If on the same domain:
• The user needs to reauthenticate and, during sign-in, choose the target organization in the browser, using the following steps:

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

• If on a different domain:
• Run the Domain Flow telling the user to choose the target organization in the browser during sign-in.

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.