Back to Browse

Prompt Optimizer Npm MCP Server

Developer ToolsUse Caution3.5MCP RegistryLocal
Free

Server data from the Official MCP Registry

Optimize prompts and generate agent SOPs and skill packages with the Prompt Optimizer cloud API.

About

Optimize prompts and generate agent SOPs and skill packages with the Prompt Optimizer cloud API.

Security Report

3.5
Use Caution3.5High Risk

The server authenticates via an OPTIMIZER_API_KEY environment variable and has no hardcoded credentials in the visible code, and its network use matches its cloud-optimization purpose. Key concerns are that user prompts and templates are sent to a third-party hosted backend by default, and that generate_harness_bundle accepts a caller-supplied output_dir for writing ZIP files; the provided code is truncated, so the full audit is incomplete. Supply chain analysis found 7 known vulnerabilities in dependencies (0 critical, 4 high severity). Package verification found 1 issue.

3 files analyzed ยท 13 issues found

Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.

Permissions Required

This plugin requests these system permissions. Most are normal for its category.

HTTP Network Access

Connects to external APIs or services over the internet.

env_vars

Check that this permission is expected for this type of plugin.

File System Write

Writes or modifies files on your machine. Check that this is expected for the tool.

What You'll Need

Set these up before or after installing:

Your Prompt Optimizer API key (starts with sk-opt-). A free key takes no card: https://promptoptimizer.xyz/dashboardRequired

Environment variable: OPTIMIZER_API_KEY

How to Install

Add this to your MCP configuration file:

{
  "mcpServers": {
    "mcp-prompt-optimizer": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-prompt-optimizer@3.8.11"
      ],
      "env": {
        "OPTIMIZER_API_KEY": "your-optimizer-api-key-here"
      }
    }
  }
}

Some servers take additional arguments. See the repository for details.

Documentation

View on GitHub

From the project's GitHub README.

MCP Prompt Optimizer

NPM Version License CI Snyk Health

๐Ÿš€ Professional cloud-based MCP server for AI-powered prompt optimization with intelligent context detection, template management, team collaboration, and enterprise-grade reliability. Starting at $0/month.

New here? A free API key takes no card and includes 20 optimizations a month. Start free, or try one optimization with no account first.

โœจ Key Features

๐Ÿง  AI Context Detection โ€” Automatically detects and optimizes for code, creative writing, image generation, communication, and more ๐Ÿ“ Template Management โ€” Auto-save high-confidence optimizations, search & reuse patterns ๐Ÿ‘ฅ Team Collaboration โ€” Shared quotas, team templates, role-based access ๐Ÿ“Š Confidence Scoring โ€” Honest quality signal with per-tier annotations โ˜๏ธ Cloud Processing โ€” Always up-to-date AI models via backend LLM pipeline ๐Ÿ”ง Resilient Fallback โ€” Structured local optimization if the backend is unreachable ๐ŸŽ›๏ธ Personal Model Choice โ€” Use your own OpenRouter models via WebUI configuration ๐Ÿ”ง Universal MCP โ€” Works with Claude Desktop, Cursor, Windsurf, Cline, VS Code, Zed, Replit


๐Ÿš€ Quick Start

1. Get your API key:

  • ๐Ÿ†“ Free Tier (sk-opt-*): 20 LLM optimizations/month, 1 API key โ€” no credit card required
  • โญ Pro (sk-opt-*): 500 optimizations/month, full model config, Context Engineer
  • ๐Ÿข Enterprise (sk-team-*): Unlimited optimizations, team keys, shared quotas

Sign up and generate your key at promptoptimizer.xyz/dashboard.

2. Install:

npm install -g mcp-prompt-optimizer

3. Connect to Claude Desktop (one command):

npx mcp-prompt-optimizer connect

This wizard reads your API key and writes the MCP server entry to Claude Desktop config automatically. Cross-platform (macOS, Windows, Linux).

Or configure manually โ€” add to ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-prompt-optimizer": {
      "command": "npx",
      "args": ["-y", "mcp-prompt-optimizer"],
      "env": {
        "OPTIMIZER_API_KEY": "sk-opt-your-key-here"
      }
    }
  }
}

4. Restart your MCP client and start optimizing.

Note: API keys are validated against the backend server. An internet connection is required (responses are cached for up to 2 hours for reliability).


โš™๏ธ How Optimization Works

Prompts are routed through a three-tier pipeline based on complexity and context. Each tier produces a different output format and confidence range.

Tier 1 โ€” LLM Optimization (backend, confidence 70โ€“95%)

The backend routes complex or high-sophistication prompts through a Gemini Flash LLM pass that genuinely rewrites and enriches the prompt. This is the highest-quality output.

# ๐ŸŽฏ Optimized Prompt

My Python script crashes with a KeyError on line 47. I need help diagnosing
the root cause. I am using Python 3.11 with pandas 2.0. The error occurs
when accessing dictionary keys after a merge operation.

**Confidence:** 82.0%
**AI Context:** code_generation

Tier 2 โ€” Backend Rules Optimization (backend, confidence < 25%)

For simpler or lower-sophistication prompts the backend applies rules-based optimization without an LLM. When this happens, confidence will be below 25% and a note will appear explaining what to check if you expected full LLM enhancement.

# ๐ŸŽฏ Optimized Prompt

My Python script crashes with a KeyError. Please provide the error message
and relevant code.

> โ„น๏ธ *Low confidence indicates the backend applied rules-based optimization
> (no LLM). Ensure `OPENROUTER_API_KEY` is configured in the backend for
> full LLM enhancement.*

**Confidence:** 18.0%
**AI Context:** code_generation

Tier 3 โ€” Local Rules Fallback (npm, confidence 35โ€“55%)

If the backend is unreachable, the npm package applies optimization locally using a library of domain-specific templates. The output is a structured, user-facing prose prompt โ€” no XML scaffolding. The confidence annotation makes the quality tier explicit.

# ๐Ÿ”ง Rules-Based Optimization Applied

โš ๏ธ *Backend unreachable โ€” your prompt has been structured using local rule
templates (no LLM). Re-run when the backend is available for full LLM
optimization.*

**Template:** `debugging_request`

**Optimized Prompt:**

My Python script crashes with a KeyError

To address this effectively:

  • Identify the most likely root causes given the error description.
  • Request the full error message and stack trace, plus the relevant code snippet.
  • Ask about expected vs. actual behavior, programming language, and library versions.

Response format: Step-by-step debugging walkthrough with a specific fix or next diagnostic steps.


**Confidence:** 51.0% *(rules-based โ€” LLM optimization typically 70โ€“95%)*
**AI Context:** code_generation

๐Ÿง  AI Context Detection

The server automatically detects your prompt type and routes it to the appropriate optimization template.

Contextai_context valueExample patterns
Code & debuggingcode_generationdebug, fix, error, python, sql, refactor
Web developmentcode_generationlanding page, react, css, html, tailwind
API & integrationapi_automationapi, rest, endpoint, oauth, webhook
DevOps & automationtechnical_automationdeploy, docker, ci/cd, terraform, bash
Data & schemasstructured_outputjson, schema, csv, yaml, transform
Analysis & researchllm_interactionanalyze, explain, compare, research
Creative writingcreative_writingstory, poem, script, blog, copywriting
Email & communicationhuman_communicationemail, letter, memo, formal, reply
Image generationimage_generationphotorealistic, midjourney, dall-e, portrait
Business & Strategybusiness_strategymarket analysis, swot, business plan
Technical Strategytechnical_strategyarchitecture, system design, migration plan
Legal & Compliancelegal_compliancecontract, gdpr, terms of service, audit
Medical & Healthmedical_healthcareclinical, diagnosis, treatment, hipaa
Educationeducational_contentlesson plan, syllabus, curriculum, quiz
Generalgeneral_assistantEverything else

Image Generation

Image prompts are handled separately. The local fallback appends style-matched quality boosters directly to the prompt (comma-separated), rather than producing structured bullets. This matches how image generation models consume prompts.

Input:  "Draw a photorealistic portrait of an astronaut"
Output: "Draw a photorealistic portrait of an astronaut, ultra realistic,
         sharp focus, professional photography, dynamic lighting, balanced
         composition, high quality, 4K"

๐Ÿ› ๏ธ Available MCP Tools

optimize_prompt

AI optimization with context detection, auto-save, and insights.

{
  "prompt": "Your prompt text",
  "goals": ["clarity", "specificity"],
  "ai_context": "code_generation"
}

detect_ai_context

Detect the AI context for a given prompt.

{
  "prompt": "The prompt text for which to detect the AI context"
}

create_template

Save an optimization as a reusable template.

{
  "title": "Template title",
  "description": "Optional description",
  "original_prompt": "The original prompt",
  "optimized_prompt": "The optimized prompt",
  "optimization_goals": ["clarity"],
  "confidence_score": 0.9,
  "ai_context_detected": "code_generation",
  "is_public": false,
  "tags": ["debugging", "python"]
}

get_template

Retrieve a saved template by ID.

{
  "template_id": "the-template-id"
}

update_template

Update an existing template.

{
  "template_id": "the-template-id",
  "title": "Updated title",
  "is_public": true
}

search_templates

Search your saved template library.

{
  "query": "debugging",
  "ai_context": "code_generation",
  "limit": 5,
  "sort_by": "confidence_score",
  "sort_order": "desc"
}

get_quota_status

Check subscription status and quota usage. No parameters required.

get_optimization_insights (conditional)

Experimental and off by default (set ENABLE_BAYESIAN_OPTIMIZATION=true to list it). It calls an analytics endpoint that the hosted service does not currently provide, so it reports that insights are unavailable; it never returns made-up data.

{
  "analysis_depth": "detailed",
  "include_recommendations": true
}

get_real_time_status (conditional)

Real-time optimization status and AG-UI capabilities. Requires the feature to be enabled in the backend; returns mock data otherwise. No parameters required.


๐Ÿค– Context Engineer (CE) Tools

Free accounts get a limited monthly Context Engineering allowance on the default model; Pro and Enterprise get more, and generate_harness_bundle requires Pro or Enterprise. CE tools generate agentic scaffolding artifacts (SOPs, skill packages, framework code) directly in your IDE.

generate_agent_sop

Generate a structured SOP document for an AI agent from a goal description. Returns markdown SOP ready for use.

{
  "goal": "What the agent should accomplish",
  "context": "Additional context, constraints, or domain info (optional)",
  "model_id": "Model to use (optional)"
}

generate_skill_package

Generate a complete skill package (SOP + SKILL.md + reference + examples + helper.py) for a given agent goal. Takes 30โ€“90 seconds (async with polling).

{
  "goal": "What the agent should accomplish",
  "format": "knowledge_doc",
  "model_id": "Model to use (optional)"
}

format currently accepts only knowledge_doc (the default); it is optional.

generate_harness_bundle

Generate a deployment-ready Agentic Harness ZIP bundle for a specific platform. Returns a confirmation when the bundle is queued for download.

{
  "goal": "The workflow goal the harness is built for",
  "deploy_target": "claude_code",
  "sop_content": "The SOP markdown content (required if no session_id)",
  "session_id": "Optional: session ID from a prior generate_skill_package call"
}

deploy_target accepts a single string (Pro+) or an array of strings (Enterprise โ€” multi-platform simultaneously). Supported targets include claude_code, langchain, autogen, crewai, amazon_q, aider, continue_dev, and more. amazon_q, aider, continue_dev, crewai require Enterprise.

explore_sop_approaches

Generate 3 parallel SOP variants (process-oriented, decision-tree, role-based) for comparison before committing to one. Returns an HTML comparison grid, a variants array, and a recommended variant. Enterprise required.

{
  "goal": "The workflow goal to generate SOP variants for",
  "context": "Optional background context",
  "blend_description": "Optional: blend all 3 variants into one SOP using this description"
}

IntentFrame fields (perspective, out_of_scope, success_definition) are also accepted to scope the generation.

transform_for_framework

Transform a SOP into native code for your agent framework: LangChain tool, AutoGen agent, or Claude Code skill.

{
  "sop_content": "The SOP markdown content",
  "goal": "What the agent should accomplish",
  "framework": "langchain_tool"
}

framework is one of langchain_tool, autogen_agent, or claude_skill.

get_ce_quota_status

Check your Context Engineer credit balance and what workflows are available at your tier. No parameters required.


๐ŸŽ›๏ธ Advanced Model Configuration (Optional)

Configure custom models in the WebUI and the MCP server uses them automatically.

Step 1 โ€” Configure in WebUI:

  1. Visit Dashboard
  2. Go to Settings โ†’ User Settings
  3. Add your OpenRouter API key (from openrouter.ai)
  4. Select your preferred models for optimization and evaluation

Step 2 โ€” Use the npm package as normal. Your WebUI model settings are applied automatically โ€” no changes to the MCP configuration required.

Model Selection Priority

1. Your WebUI-configured models  (highest priority)
2. Request-specific model override
3. System default (google/gemini-flash-1.5-8b)

Example Model Recommendations

Use caseOptimization modelEvaluation model
Creative / complexanthropic/claude-3-5-sonnetgoogle/gemini-pro-1.5
Fast / simpleopenai/gpt-4o-miniopenai/gpt-3.5-turbo
Code / technicalanthropic/claude-3-5-sonnetanthropic/claude-3-haiku

Two different API keys:

  • Service key (sk-opt-* or sk-team-*) โ€” your MCP Prompt Optimizer subscription
  • OpenRouter key โ€” your personal OpenRouter account for model usage costs

๐Ÿ’ฐ Subscription Plans

PlanPriceOptimizations/monthCE CreditsAPI Keys
๐Ÿ†“ Free$020 LLMโ€”1
โญ Pro$19/mo50051
๐Ÿข EnterpriseCustomUnlimited5010 (shared)

All plans include AI context detection, template management, personal model configuration, and optimization insights.

Get started free โ†’


๐Ÿ”ง CLI Commands

npx mcp-prompt-optimizer connect        # Interactive wizard: add API key to Claude Desktop config
mcp-prompt-optimizer check-status       # Check API key and quota status
mcp-prompt-optimizer validate-key       # Validate API key with backend
mcp-prompt-optimizer diagnose           # Run comprehensive diagnostic
mcp-prompt-optimizer clear-cache        # Clear validation cache
mcp-prompt-optimizer help               # Show help and setup instructions
mcp-prompt-optimizer version            # Show version information

๐Ÿข Team Collaboration

Team API Keys (sk-team-*)

  • Shared quotas across team members
  • Centralized billing and management
  • Team template libraries for consistency
  • Role-based access control

Individual API Keys (sk-opt-*)

  • Personal quotas and billing โ€” available on Free and Pro tiers
  • Individual template libraries
  • Account self-management

๐Ÿ” Security & Privacy

  • Encrypted data transmission
  • API key validation with secure backend authentication
  • Quota enforcement with real-time usage tracking
  • Prompts you optimize and the results are sent to the Prompt Optimizer API over HTTPS and stored in your account's optimization history. You can delete that history and your saved templates in the dashboard, or request account deletion. See the privacy policy
  • If the backend is unreachable, the package falls back to a limited optimization that runs on your machine
  • GDPR compliant

Files this package writes on your machine

  • ~/.mcp-cloud-api-cache.json and ~/.mcp-cloud-health.json: a cache of your key's validation result and network-health counters. mcp-prompt-optimizer clear-cache removes them.
  • generate_harness_bundle saves the ZIP it generates under OPTIMIZER_OUTPUT_DIR (default: a mcp-prompt-optimizer folder in the system temp directory), with a timestamped name; it never overwrites. The tool's optional output_dir argument may only name a subfolder of that location. To save elsewhere, set OPTIMIZER_OUTPUT_DIR in your own environment.
  • npx mcp-prompt-optimizer connect edits your MCP client's config file (a .bak backup is written first).

๐Ÿ”ง Universal MCP Client Support

Claude Desktop

{
  "mcpServers": {
    "mcp-prompt-optimizer": {
      "command": "npx",
      "args": ["-y", "mcp-prompt-optimizer"],
      "env": { "OPTIMIZER_API_KEY": "sk-opt-your-key-here" }
    }
  }
}

Cursor IDE

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "mcp-prompt-optimizer": {
      "command": "npx",
      "args": ["-y", "mcp-prompt-optimizer"],
      "env": { "OPTIMIZER_API_KEY": "sk-opt-your-key-here" }
    }
  }
}

Other clients

Windsurf, Cline, VS Code, Zed, Replit, JetBrains IDEs, and Neovim are all supported via standard MCP server configuration.


๐Ÿ“ฆ Changelog

v3.7.2

  • Stdout / JSON-RPC safety โ€” All MCP server startup logs (banner, status, mode indicators, key validation) now route to stderr instead of stdout. On stdio transports stdout is the JSON-RPC channel; previously any non-protocol writes there risk corrupting the stream. No user-facing change beyond logging.
  • Contract test โ€” npm run test:contract pins the /optimize response shape (Pydantic fields + runtime-injected quota_used/quota_limit + metadata routing_score/routing_tier/model_used) against a canonical fixture. Catches backend drift before publish.
  • CI workflow โ€” .github/workflows/ci.yml runs npm ci + health check + contract check on push/PR across Node 18, 20, and 22.

v3.6.0

  • Free tier MCP access โ€” Free users can now create an API key (sk-opt-*) and use the MCP server at no cost (currently 20 LLM optimizations/month). Previously, key creation was blocked in the live service due to a bug introduced when the free-tier launch landed in an unused module. Keys with subscription_status: NULL (all free accounts) now validate correctly.
  • connect wizard โ€” npx mcp-prompt-optimizer connect interactively writes your API key to Claude Desktop config on macOS, Windows, and Linux. Replaces manual JSON editing for new users.
  • Upsell block โ€” Local rules fallback output now includes a concise upgrade prompt with a one-command onboarding path when no API key is configured.

v3.5.0

  • LLM upsell block added to local fallback output
  • connect subcommand added (interactive Claude Desktop config wizard)

v3.4.1

  • Tier names migrated from Explorer/Creator/Innovator to Free/Pro/Enterprise (D6 pricing)

v3.4.0

  • explore_sop_approaches tool: generates 3 parallel SOP variants (process-oriented, decision-tree, role-based) for comparison before committing. Optionally accepts blend_description to blend variants directly. Enterprise tier required.

v3.3.0

  • generate_harness_bundle tool: generates deployment-ready ZIP harness for 14+ platforms. Single deploy target (Pro+) or multi-platform array (Enterprise).
  • Intent frame fields (perspective, out_of_scope, success_definition) added to generate_agent_sop for scoped SOP generation.

v3.2.x

  • transform_for_framework tool: converts SOP to native LangChain tool, AutoGen agent, or Claude Code skill
  • CE harness HTML review layer with interactive DAG visualization

v3.0.3

  • Rules fallback output rewritten โ€” local optimization now produces user-facing prose prompts instead of raw XML scaffolding. The output is directly usable as a prompt without modification.
  • All 18 local templates reworded โ€” template principles are now phrased as user request guidance rather than AI-assistant directives, producing more natural and actionable structured prompts.
  • creative_writing context now routes correctly to the creative writing template (previously fell through to a generic fallback).
  • general_assistant context now maps explicitly to the LLM interaction template.
  • Backend rules-tier detection โ€” when the backend returns confidence below 25% (indicating it ran its own rules tier without an LLM), a note appears explaining the cause and how to resolve it (OPENROUTER_API_KEY configuration).
  • Confidence scale annotation โ€” rules-based fallback confidence now shows *(rules-based โ€” LLM optimization typically 70โ€“95%)* so users understand where their result sits relative to full LLM optimization.

v3.0.2

  • Cross-platform binary compatibility improvements
  • Bayesian optimization integration
  • AG-UI feature flag support

v3.0.0

  • API key now required for all operations
  • Development mode and offline mode removed for security
  • All keys validated against backend server

๐Ÿ› ๏ธ Support & Resources


Start free at promptoptimizer.xyz โ€” 20 LLM optimizations/month, no credit card required.

Reviews

No reviews yet

Be the first to review this server!