MCP Server New Relic — NRQL queries via NerdGraph, alert policy listing, custom event recording, and /health check

SDK setup and authentication

New Relic does not publish an official Node.js client for NerdGraph — the API is a standard GraphQL endpoint, so axios with a shared instance is the idiomatic approach. The credential is called a "User Key" in New Relic's UI even when used for programmatic server-to-server access; the header name is Api-Key (not Authorization: Bearer). Your Account ID is a numeric identifier required by most NRQL and alert queries — find it in the New Relic UI under User menu → API Keys → Account ID.

import axios from 'axios';

const nerdgraph = axios.create({
  baseURL: 'https://api.newrelic.com',
  headers: {
    'Api-Key': process.env.NEW_RELIC_USER_KEY!,
    'Content-Type': 'application/json',
  },
});

const ACCOUNT_ID = parseInt(process.env.NEW_RELIC_ACCOUNT_ID!, 10);

async function nrQuery(query: string, variables: Record<string, unknown> = {}) {
  const res = await nerdgraph.post('/graphql', { query, variables });
  if (res.data.errors?.length) {
    throw new Error(`NerdGraph error: ${res.data.errors[0].message}`);
  }
  return res.data.data;
}

For EU data centers, replace api.newrelic.com with api.eu.newrelic.com and the Events collector URL (insights-collector.newrelic.com) with insights-collector.eu01.nr-data.net. The Api-Key header name and authentication mechanism are identical across regions.

Running NRQL queries via NerdGraph

NRQL (New Relic Query Language) queries execute through NerdGraph using a nested GraphQL structure: actor → account(id) → nrql(query). Results come back as an array of plain objects at data.actor.account.nrql.results. NRQL syntax is SQL-like — SELECT, FROM, WHERE, SINCE, UNTIL, FACET, and TIMESERIES are the primary clauses. The rate limit is 25 concurrent NerdGraph requests per API key and 600 requests per minute.

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { z } from 'zod';

const server = new McpServer({ name: 'newrelic-mcp', version: '1.0.0' });

const NRQL_QUERY = `
  query NrqlQuery($accountId: Int!, $nrql: Nrql!) {
    actor {
      account(id: $accountId) {
        nrql(query: $nrql) {
          results
        }
      }
    }
  }
`;

server.tool('query_nrql', {
  nrql_query: z.string()
    .describe('NRQL query string. Example: SELECT average(duration) FROM Transaction WHERE appName = \'my-app\' SINCE 1 hour ago LIMIT 100'),
  account_id: z.number().int().optional()
    .describe('New Relic account ID. Defaults to the account set in NEW_RELIC_ACCOUNT_ID env var.')
}, async ({ nrql_query, account_id }) => {
  const accountId = account_id ?? ACCOUNT_ID;

  const data = await nrQuery(NRQL_QUERY, {
    accountId,
    nrql: nrql_query
  });

  // Results live at data.actor.account.nrql.results — an array of objects
  const results = data.actor.account.nrql.results as Record<string, unknown>[];

  return {
    content: [{
      type: 'text',
      text: JSON.stringify({
        account_id: accountId,
        query: nrql_query,
        result_count: results.length,
        results
      }, null, 2)
    }]
  };
});

Listing alert policies with incident preference

Alert policies in New Relic group alert conditions and control how incidents are opened. The incidentPreference field determines granularity: PER_POLICY opens one incident per policy regardless of how many conditions fire, PER_CONDITION opens one incident per firing condition, and PER_CONDITION_AND_TARGET is the most granular — one incident per condition per monitored entity. Creating or modifying alert conditions via API is complex and error-prone; keep MCP tools read-only for policy inspection.

const LIST_POLICIES_QUERY = `
  query ListAlertPolicies($accountId: Int!) {
    actor {
      account(id: $accountId) {
        alerts {
          policiesSearch {
            policies {
              id
              name
              incidentPreference
            }
          }
        }
      }
    }
  }
`;

server.tool('list_alert_policies', {
  account_id: z.number().int().optional()
    .describe('New Relic account ID. Defaults to NEW_RELIC_ACCOUNT_ID env var.')
}, async ({ account_id }) => {
  const accountId = account_id ?? ACCOUNT_ID;

  const data = await nrQuery(LIST_POLICIES_QUERY, { accountId });

  const policies = data.actor.account.alerts.policiesSearch.policies as Array<{
    id: string;
    name: string;
    incidentPreference: string;
  }>;

  return {
    content: [{
      type: 'text',
      text: JSON.stringify({
        account_id: accountId,
        policy_count: policies.length,
        policies: policies.map(p => ({
          id: p.id,
          name: p.name,
          incident_preference: p.incidentPreference,
          // incidentPreference meanings:
          // PER_POLICY: one incident per policy (all conditions share an incident)
          // PER_CONDITION: one incident per firing condition
          // PER_CONDITION_AND_TARGET: most granular — one per condition per entity
        }))
      }, null, 2)
    }]
  };
});

For accounts using New Relic's older REST v2 alert data, the legacy endpoint GET https://api.newrelic.com/v2/alert_policies.json with the same Api-Key header returns policies in a flat JSON structure. NerdGraph is preferred for new integrations as it includes richer metadata and supports cursor-based pagination via policiesSearch(cursor: $cursor) for accounts with large numbers of policies.

Recording custom events via the Insights Collector API

Custom events use a completely separate API from NerdGraph — the Insights Collector endpoint — and require a different credential: an Insert Key (not a User Key). The Insert Key is write-only and cannot read any data, making it safe to deploy in CI pipelines or agent runtimes. Once recorded, custom events are immediately queryable via NRQL using the eventType value as the FROM table name.

import axios from 'axios';

// Insert Key (separate from User Key) — header is X-Insert-Key
const insightsCollector = axios.create({
  baseURL: `https://insights-collector.newrelic.com/v1/accounts/${ACCOUNT_ID}`,
  headers: {
    'X-Insert-Key': process.env.NEW_RELIC_INSERT_KEY!,
    'Content-Type': 'application/json',
  },
});

server.tool('record_custom_event', {
  event_type: z.string()
    .regex(/^[a-zA-Z][a-zA-Z0-9_]{0,254}$/, 'eventType must start with a letter, contain only alphanumeric and underscores, max 255 chars')
    .describe('The event type — becomes the table name in NRQL (e.g. "Deployment", "FeatureFlag", "CacheEviction").'),
  attributes: z.record(z.union([z.string(), z.number(), z.boolean()]))
    .describe('Key-value attributes to attach to the event. Values must be string, number, or boolean.')
}, async ({ event_type, attributes }) => {
  // Body is a JSON array — you can batch multiple events in one request
  const payload = [{ eventType: event_type, ...attributes }];

  const res = await insightsCollector.post('/events', payload);

  // Success returns HTTP 200 with { success: true }
  return {
    content: [{
      type: 'text',
      text: JSON.stringify({
        success: res.data.success,
        event_type,
        attributes,
        // Query immediately after recording:
        nrql_to_verify: `SELECT * FROM ${event_type} SINCE 1 hour ago`
      }, null, 2)
    }]
  };
});

Example deployment event payload and its corresponding NRQL query:

// Record a deployment event
const deploymentEvent = [{
  eventType: 'Deployment',
  service: 'checkout',
  version: '1.2.3',
  deployer: 'ci-bot',
  environment: 'production',
  commit_sha: 'a1b2c3d4'
}];

// After posting, query via NRQL:
// SELECT * FROM Deployment SINCE 1 hour ago
// SELECT count(*) FROM Deployment FACET service SINCE 7 days ago

Wiring /health/newrelic via NerdGraph user query

The NerdGraph health probe uses a minimal query that fetches the authenticated user's name and email. Because NerdGraph always returns HTTP 200 — even for invalid or expired API keys — you must inspect the response body: a populated data.actor.user object means healthy, while an errors array in the response body means the key is invalid or lacks permissions. Never treat HTTP 200 alone as a health signal for NerdGraph.

const HEALTH_QUERY = `
  {
    actor {
      user {
        name
        email
      }
    }
  }
`;

app.get('/health/newrelic', async (req, res) => {
  try {
    const response = await nerdgraph.post('/graphql', { query: HEALTH_QUERY });

    // NerdGraph always returns HTTP 200 — check the body for errors
    if (response.data.errors?.length) {
      return res.status(503).json({
        status: 'unhealthy',
        // Common error: "User authentication failed" when key is expired or revoked
        error: response.data.errors[0].message,
        type: response.data.errors[0].extensions?.errorClass
      });
    }

    const user = response.data.data?.actor?.user;

    if (!user) {
      return res.status(503).json({
        status: 'unhealthy',
        error: 'NerdGraph returned no user data — key may lack permissions'
      });
    }

    return res.json({
      status: 'healthy',
      user_name: user.name,
      user_email: user.email,
      account_id: ACCOUNT_ID
    });
  } catch (err: any) {
    // A true HTTP error (network failure, timeout, or HTTP 403 format error)
    // HTTP 403 from NerdGraph means the request format is wrong, NOT an auth error
    return res.status(503).json({
      status: 'unhealthy',
      http_status: err.response?.status,
      error: err.message
    });
  }
});

Frequently asked questions

Further reading

• MCP Server Datadog — query metrics, list monitors, post events
• MCP Server AWS CloudWatch
• MCP Server Health Check — wiring /health endpoints for uptime monitoring
• MCP Server Error Handling — structured errors and retry patterns
• Building MCP Tools for DevOps Platforms