PromptLayer MCP Server

MCP server that wraps the PromptLayer REST API, giving any MCP-compatible client access to all 33 PromptLayer tools.

Setup

npm install

Set your API key:

export PROMPTLAYER_API_KEY=pl_your_key_here

Or create a .env file (see .env.example).

Usage

With Claude Desktop

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "promptlayer": {
      "command": "npx",
      "args": ["-y", "@promptlayer/mcp-server"],
      "env": {
        "PROMPTLAYER_API_KEY": "pl_your_key_here"
      }
    }
  }
}

With Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "promptlayer": {
      "command": "npx",
      "args": ["-y", "@promptlayer/mcp-server"],
      "env": {
        "PROMPTLAYER_API_KEY": "pl_your_key_here"
      }
    }
  }
}

From source

npm run build
node build/index.js

Tools

Prompt Templates

| Tool | Description | |---|---| | get-prompt-template | Get a template by name/ID with optional version or release label. Returns provider-formatted llm_kwargs. | | get-prompt-template-raw | Get raw template data without filling variables. For sync, caching, inspection. | | list-prompt-templates | List templates with pagination. Filter by name, label, status. | | publish-prompt-template | Create a new version of a template with content, metadata, and release labels. | | list-prompt-template-labels | List release labels on a template. | | create-prompt-label | Attach a release label to a template version. | | move-prompt-label | Move a label to a different version. | | delete-prompt-label | Delete a label. | | get-snippet-usage | Find all templates referencing a snippet. |

Tracking

| Tool | Description | |---|---| | log-request | Log an LLM request/response pair. Input/output in Prompt Blueprint format. | | track-prompt | Link a logged request to a prompt template. | | track-score | Score a logged request (0-100). Supports named scores. | | track-metadata | Attach metadata to a logged request. | | track-group | Associate a request with a group. | | create-spans-bulk | Create OpenTelemetry spans in bulk for tracing. |

Datasets

| Tool | Description | |---|---| | list-datasets | List datasets with filtering. | | create-dataset-group | Create a dataset group (container for versions). | | create-dataset-version-from-file | Create a version from base64 CSV/JSON. | | create-dataset-version-from-filter-params | Create a version from request log history. |

Evaluations

| Tool | Description | |---|---| | list-evaluations | List evaluation pipelines. | | create-report | Create an evaluation pipeline on a dataset. | | run-report | Execute a pipeline. | | get-report | Get pipeline details. | | get-report-score | Get the computed score. | | add-report-column | Add an evaluation step (one per request). | | update-report-score-card | Configure custom scoring logic. | | delete-reports-by-name | Archive pipelines by name. |

Agents

| Tool | Description | |---|---| | list-workflows | List all agents. | | create-workflow | Create an agent or new version. | | patch-workflow | Partially update an agent. | | run-workflow | Execute an agent by name. | | get-workflow-version-execution-results | Poll for execution results. |

Other

| Tool | Description | |---|---| | create-folder | Create a folder for organizing resources. |

Keeping in Sync

Schemas are verified against the PromptLayer OpenAPI spec. Run:

npm run sync:check

This fetches the spec, extracts our tool schemas, and diffs them structurally. Exit 0 = in sync. See TESTING.md for details.

Development

npm run dev       # Run with tsx (hot reload)
npm run build     # Compile TypeScript
npm run watch     # Watch mode

Project Structure

src/
  index.ts      # Entry point, starts MCP server
  types.ts      # Zod schemas + TOOL_DEFINITIONS for all 33 tools
  client.ts     # HTTP client for PromptLayer API
  handlers.ts   # Registers all tools with the MCP server
  utils.ts      # Shared utilities (query params, error handling, handler factory)
scripts/
  fetch-openapi-endpoints.ts   # Downloads + extracts OpenAPI spec
  extract-mcp-tools.ts         # Extracts MCP tool schemas for comparison
  diff-endpoints.ts            # Structural diff with known exceptions