@sysdig/mcp-core

Product-agnostic plumbing for building Model Context Protocol servers on top of Sysdig REST APIs.

This package contains everything that is not specific to a single Sysdig product: transport selection (stdio + streamable HTTP), the OAuth2 proxy, credential/env resolution, the SysdigClient fetch wrapper, Prometheus metrics, optional Telecaster instrumentation, the shared platform tools (3 customer/user tools plus 13 platform IAM tools for teams/users/roles), the tool-authoring kit, and the e2e testkit. A product package (e.g. @sysdig/secure-mcp-server) consumes it, registers its own domain tools, and hands the result to startServer().

Installation

npm install @sysdig/mcp-core zod

zod is a peer dependency (^3.25 || ^4.0); install it alongside this package.

Usage

import { startServer } from "@sysdig/mcp-core";
import { getClient, toolError, READ_ONLY, WRITE } from "@sysdig/mcp-core";

startServer({
  product: "SDS",                 // Sysdig product code (SDS = Secure, SDC = Monitor)
  serverName: "sysdig-secure",
  serverVersion: "1.0.0",
  metricsPrefix: "secure_mcp_",
  logPrefix: "[secure-mcp-server]",
  registerTools(server) {
    // Core auto-registers the shared platform tools first, then calls this.
    server.registerTool(
      "my_tool",
      { description: "…", inputSchema: { /* zod */ }, annotations: READ_ONLY },
      async (params, extra) => {
        const client = getClient(extra.sessionId);
        const data = await client.get("/some/endpoint");
        return { content: [{ type: "text", text: JSON.stringify(data) }] };
      },
    );
  },
});

startServer(config)

Boots the whole server given a ServerConfig. Transport is selected via the SYSDIG_MCP_TRANSPORT env var (stdio default, or http). Everything product-specific is threaded through ServerConfig; everything else is read from process.env.

| Field | Required | Description | | --- | --- | --- | | product | yes | Sysdig product code, threaded into the OAuth _product= param | | serverName | yes | MCP server name advertised to clients | | serverVersion | yes | MCP server version advertised to clients | | registerTools | yes | Callback that registers product tools on the McpServer | | metricsPrefix | yes | Prometheus metric name prefix | | defaultHost | no | Last-resort fallback host (default https://app.sysdigcloud.com) | | logPrefix | no | Log-line prefix | | serviceDocumentationUrl | no | Documentation URL advertised in OAuth metadata |

Tool-authoring kit

Domain tools import their helpers from this package, not from a relative path:

• getClient(sessionId) — resolves the SysdigClient (stdio singleton or per-session HTTP client).
• toolError(...) — builds a standard MCP error result.
• READ_ONLY / WRITE — tool annotation presets.

Every SysdigClient request method (get, getOrNull, getText, post, put, patch, delete) accepts an optional trailing RequestOptions argument for call-specific overrides. Its headers are merged over the client's defaults (Authorization, Content-Type, Accept), with caller-supplied values winning on key collision — e.g. to attach an x-sysdig-request-metadata header on a single call:

await client.get("/prometheus/api/v1/query", {
  headers: { "x-sysdig-request-metadata": JSON.stringify({ source: "sysdig_mcp" }) },
});

Testkit

End-to-end helpers live under the @sysdig/mcp-core/testkit entry point (matrix reconciliation, the spawn-over-stdio runner, pickFirstId, reporting).

License

Proprietary — © Sysdig, Inc. See the repository for details.