MCP reference

The Prometheus MCP server exposes the agent-to-agent surface as native Model Context Protocol tools, so any MCP client (Claude Desktop, Claude Code, Cursor, etc.) can ask Prometheus for verified Firecrawl code and manage self-healing scripts and deployments without any HTTP plumbing.

It is a thin wrapper: every tool calls /api/v1/* on a running Prometheus instance (see the API reference).

Installation

1. Install dependencies

The server needs @modelcontextprotocol/sdk and zod:

cd mcpnpm install

This produces a runnable mcp/server.mjs (also exposed as the prometheus-mcp bin if you npm i -g the package).

2. Make sure a Prometheus instance is reachable

The server forwards to an instance; it does not run the agent itself. Have one running (e.g. npm run dev, serving http://localhost:3000) or deployed.

3. Register the server with your client

The server speaks stdio. Configuration is the same shape everywhere — a command, its args, and env vars.

Claude Desktop — claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{  "mcpServers": {    "prometheus": {      "command": "node",      "args": ["/absolute/path/to/prometheus/mcp/server.mjs"],      "env": {        "PROMETHEUS_URL": "http://localhost:3000",        "PROMETHEUS_TOKEN": ""      }    }  }}

Claude Code — add it with the CLI:

claude mcp add prometheus \  --env PROMETHEUS_URL=http://localhost:3000 \  --env PROMETHEUS_TOKEN= \  -- node /absolute/path/to/prometheus/mcp/server.mjs

Cursor / other clients — use the same command + args + env triple in that client's MCP config.

Configuration

After registering, restart the client. You should see the prometheus_* tools available.

Tools

Input/return shapes mirror the HTTP API exactly — see the API reference for field details, the schedule grammar (every), self-heal strategies, and the Script/Deployment/Run objects. Errors are returned as MCP tool errors (isError: true) with the instance's message, not as crashes.

prometheus_build

The headline tool. Given a natural-language data request, returns a TypeScript collector (script) that reliably produces the data, plus a sample of that data. The calling agent embeds script directly. Runs the agent headlessly (~30–180s); makes reasonable assumptions and reports them in howItWorks. Pass schema (a JSON Schema object) to enforce an exact output shape, or urls to pin starting pages.

prometheus_script_* / prometheus_deployment_*

A script is the versioned, self-healing collector; a deployment is one way it runs (scheduled, on-demand, or both). Build once with prometheus_build, then save it with prometheus_script_create({ sessionId, deployment: { every } }); or pass a prompt to build-and-save in one call. Use prometheus_deployment_run({ id }) when you need fresh data (the collected JSON comes back inline), prometheus_deployment_data({ id }) for the last collected dataset, or prometheus_script_data({ id }) for the freshest data across all of a script's deployments.

Implementation

The server is plain JavaScript with no Prometheus-specific logic — it just shapes MCP tool calls into HTTP requests.

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";import { z } from "zod";
// every tool funnels through one helper:async function api(method, path, body) {  const headers = { "content-type": "application/json" };  if (TOKEN) headers.authorization = `Bearer ${TOKEN}`;  const res = await fetch(`${BASE}${path}`, { method, headers, body: body && JSON.stringify(body) });  // …parse JSON, throw a clean Error on non-2xx…}
// tools are registered with zod input schemas and a thin handler:server.registerTool(  "prometheus_build",  { title, description, inputSchema: { prompt: z.string(), schema: z.record(z.any()).optional(), urls: z.array(z.string()).optional() } },  tool(({ prompt, schema, urls }) => api("POST", "/api/v1/build", { prompt, schema, urls })),);
await server.connect(new StdioServerTransport());

Because it is a pure passthrough: no state lives in the server (scripts, deployments, sessions, and artifacts all live in the Prometheus instance), response shapes always match the API, and it is safe to run anywhere the instance is reachable.

MCP vs. the other surfaces

• MCP — best for chat-style agents that call tools natively (Claude Desktop, Cursor). Zero glue code.
• CLI — best for agents that work at a shell or write code; pipeable. See the CLI reference.
• HTTP API — the universal contract everything else wraps; call it from any language. See the API reference.
• Skill — an installable Agent Skill that teaches a coding agent when and how to reach for Prometheus (uses the CLI/API).