Product

MCP client integration

PromptFlowEngine speaks the Model Context Protocol, so any MCP client (GitHub Copilot agent mode, Claude Desktop, Claude Code, Cursor, or your own agent) can call the engine as tools. Your assistant can then check, restructure, and sanitize a prompt as a step in its own work instead of you doing it by hand.

A note on terms: the piece you install is an MCP server (@promptflow/mcp-server v2.1.0, server name promptflow-engine). Your AI tool is the MCP client that connects to it.

Setup for Claude Code, Windsurf, and Gemini CLI, a TypeScript client example, and troubleshooting: Connect PromptFlowEngine.

How it connects

connection

MCP client (Copilot, Claude, Cursor, your agent)
   │  spawns a local process and talks JSON-RPC over stdio
   ▼
promptflow-mcp  (node packages/mcp-server/dist/bin.js)
   │  validates arguments, runs the engine in-process
   ▼
@promptflow/engine   no network, no model calls, no files read

The transport is stdio only. The server runs on your machine as a child process of the client, reads nothing but the arguments it is given, and makes no network calls.

Authentication

None is needed and none is supported: there is no API key, account, or token. Access is controlled by your operating system, since only a process you start can talk to the server over its stdin and stdout. There is no hosted or HTTP MCP endpoint; for remote use, call the HTTP API instead.

Configure

Build it from a checkout of the PromptFlowEngine repository (npm publishing is pending), then point your client at dist/bin.js:

shell

pnpm --filter @promptflow/engine build && pnpm --filter @promptflow/mcp-server build

VS Code / Copilot: .vscode/mcp.json

{
  "servers": {
    "promptflow": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/checkout/packages/mcp-server/dist/bin.js"]
    }
  }
}

Claude Desktop, Cursor, and other clients

{
  "mcpServers": {
    "promptflow": { "command": "node", "args": ["/absolute/path/to/checkout/packages/mcp-server/dist/bin.js"] }
  }
}

The VS Code extension bundles the same server and writes the first entry for you.

Environment variable	Default	Purpose
`PROMPTFLOW_MCP_MAX_PROMPT_CHARS`	`100000`	Maximum characters per text argument (hard ceiling 2,000,000).
`PROMPTFLOW_MCP_LOG`	unset	`debug` logs tool name, input size, outcome, and duration to stderr. Never content.

Capabilities: tools (19)

Tool	Description
`optimize_prompt`	Optimize a prompt with deterministic, verified transforms (duplicates, filler, optional sections). Every candidate is checked to preserve all sentences, requirements, code, and variables; the original is kept if nothing is better. Returns the selected prompt, token savings, quality score, and what changed.
`optimize_prompt_pipeline`	Run the optimization pipeline and return per-stage results plus token and estimated cost metrics, in the result shape used by the PromptFlow VS Code extension.
`compress_prompt`	Remove exact duplicate sentences and extra whitespace without rewriting any wording.
`validate_prompt`	Check a prompt for missing objective or output format, ambiguity, conflicting instructions, duplicates, prompt-injection patterns, secrets, and undelimited variables. isValid is false only when a critical issue exists.
`estimate_tokens`	Count tokens and estimate input cost for a model. "exact" is true only for OpenAI models with a loaded tokenizer; other providers are approximate. Costs are estimates from a reference price table.
`analyze_prompt`	Detect intent, task type, technical domain, requested output, requirements, and entities (languages, frameworks, file paths, identifiers).
`extract_entities`	Extract languages, frameworks, libraries, cloud platforms, services, technologies, file paths, identifiers, URLs, and commands.
`summarize_context`	Extractive summary: the first N unique, non-empty sentences of a context block, in order. Does not rank or rewrite.
`score_prompt`	Score prompt quality 0-100: 100 minus a penalty per issue (critical 30, warning 10, info 3; capped at 50 with any critical issue), with per-dimension scores and suggestions.
`evaluate_prompt`	Full quality report: overall score, grade, eight quality dimensions with the checks that failed, and every finding with why it matters and how to fix it.
`compare_prompts`	Compare two prompts: token and estimated cost delta, quality delta per dimension, and which findings were resolved or introduced.
`scan_prompt_security`	Prompt-injection risk (0-100, signature-based, with threat ids), sensitive-data counts by category, undelimited template variables, and destructive operations. Never returns detected secret values.
`scan_sensitive_data`	Scan text for credentials, cloud secrets, and PII with local deterministic detectors. Returns offsets and per-category counts, never the sensitive values.
`sanitize_prompt`	Replace detected sensitive data with placeholders such as [REDACTED_API_KEY]. Returns the sanitized text and counts, never the original values. Use before sending a prompt to an external model.
`restructure_prompt`	Turn a loosely written request into a sectioned engineering prompt: Role, Objective, Context, Requirements, Constraints, Edge cases, Testing, Acceptance criteria, Expected output. Only sections with content appear. The author's clauses are kept and reordered; for software tasks, fixed engineering guidance chosen by intent and topic is added, and every line is labeled "prompt" or "engine" so additions can be reviewed. Set scaffold=false to reorganize without adding guidance.
`convert_structured_payload`	Convert a JSON payload to TOON (Token-Oriented Object Notation) and say whether to use it. Returns token counts for pretty JSON, compact JSON and TOON, a round-trip check (the TOON must decode back to the same value), and the recommendation: "toon" only when it round-trips and saves at least 5 % over compact JSON, otherwise "json". Lossless or it keeps JSON.
`simulate_cost`	Simulate what a prompt costs across models at a request volume, from catalog list prices (labelled simulated, never a bill). Optionally optimizes the prompt first and reports hypothetical savings. Flags models whose context window is too small.
`analyze_context_budget`	Measure the context sources you intend to send with a prompt: tokens and share per source, context-window usage with an output reserve, sensitive data (categories and counts only), instruction-like text in retrieved sources, and duplicates. Reads only the text passed in; never reads files.
`run_prompt_tests`	Run a regression suite against a prompt. Assertions check the prompt (contains, not_contains, matches, max_tokens, min_quality, no_finding, max_severity, has_variables, max_injection_risk, no_sensitive_data, output_format) and, when a case carries a recorded model response, the response (response_valid_json, response_has_keys, response_contains, response_max_chars). With baseline_prompt, also runs the suite on the baseline and lists cases that regressed. No model is called.

All tools are annotated read-only and idempotent. The first eleven keep the exact result fields they had in the 1.5.x extension, so existing agent configurations keep working.

Resources and prompts

promptflow://rules: the rule catalogue, dimensions, and scoring penalties.
promptflow://models: models, token encodings, and reference prices.
Prompt review-prompt: asks the assistant to evaluate and optimize a prompt, with the prompt wrapped in tags as data.

Example

In an agent chat, ask in plain language and the client picks the tool:

you

Use promptflow to restructure this before you start:
"fix login issue and make google login work and don't break anything"

tools/call the client sends

{
  "name": "restructure_prompt",
  "arguments": { "prompt": "fix login issue and make google login work and don't break anything" }
}

result (abridged)

{
  "restructuredPrompt": "## Role\nAct as a senior software engineer.\n\n## Objective\nFix login issue and make Google login work.\n…",
  "intent": "debugging",
  "topics": ["authentication"],
  "counts": { "prompt": 4, "engine": 20, "codebase": 0 }
}

To try it without a client, pipe JSON-RPC to the process:

shell

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"cli","version":"1"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"estimate_tokens","arguments":{"prompt":"Hello, world!","model":"gpt-4o"}}}' \
  | node packages/mcp-server/dist/bin.js

Errors and security

Arguments are validated with a schema. Bad or oversized arguments return a tool error (isError) with the reason, not a protocol error, so agents can correct and retry.
No tool returns detected secret values: sensitive-data results carry categories and offsets only.
Prompt text passed to a tool is treated as data. The server never executes it, and the review-prompt template wraps it in tags for the model.
The server has no file, shell, or network tools, so a prompt-injected agent cannot use it to reach anything.