MCP Prompt Optimizer

🚀 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

Related MCP server: PromptVault MCP Server

🚀 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.

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

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

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

• 📖 Documentation: promptoptimizer.xyz/docs

• 📊 Dashboard & model config: promptoptimizer.xyz/dashboard

• 🚀 Pricing & API Keys: promptoptimizer.xyz/pricing

• 🐛 Issues: GitHub Issues

• 📄 License: Commercial License

• 🔒 Security: Security Policy

• 🤝 Contributing: Contributing Guide

• 📜 Code of Conduct: Contributor Covenant

• 📝 Changelog: Release History

• 📧 Email support: support@promptoptimizer.xyz

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