March 23, 2026

OpenClaw – Security

 

A Security Analysis of OpenClaw

From a security perspective, the core problem is not one isolated bug. The real risk comes from the combination of three conditions: high local privileges, exposure to external input, and automatic tool execution. OpenClaw’s own security guidance explicitly frames it as a personal assistant operating within a single trusted-operator boundary, not as a hardened hostile multi-tenant platform for mutually untrusted users. CNCERT has also issued a dedicated risk warning about OpenClaw deployments and usage.

As of March 23, 2026, the official OpenClaw threat model draft lists 37 total threats, including 6 rated Critical. Those threats span the agent runtime, gateway, skills ecosystem, extensions, and client surfaces. That alone suggests an important conclusion: OpenClaw should be understood as a system with a broad and evolving attack surface, not as a product where fixing a single CVE makes the deployment “safe.”

The first major category of risk is authentication and permission-boundary failure. Several public advisories show how easily identity, pairing, or control-plane trust can become the weakest link. CVE-2026-28472 describes a flaw in the gateway WebSocket handshake that allowed device identity checks to be skipped when a token was merely present rather than properly validated. CVE-2026-32057 covers an authentication bypass in the trusted-proxy Control UI pairing mechanism, where a client could claim the control-ui identity without correct device verification. The common root cause in these cases is straightforward: the system treated “appears internal” or “has some auth material” as equivalent to “has completed trustworthy identity binding.”

The second category is prompt injection and trust-boundary confusion. One of the clearest examples is CVE-2026-24764, in which Slack channel metadata such as topics or descriptions could be incorporated into the model’s system prompt. That widened the injection surface by allowing untrusted channel metadata to be interpreted as higher-trust control input. In practical terms, once multiple partially trusted or untrusted users, channels, or group chats are allowed to steer a tool-enabled agent, ordinary messages can stop being “just content” and start becoming effective control instructions. That is especially dangerous in an agent that can invoke tools, read secrets, or act on the host system.

The third category is command execution and sandbox failure, which is arguably the most dangerous layer because it moves the impact from “the model was manipulated” to “the host system can be compromised.” CVE-2026-24763 describes command injection in OpenClaw’s Docker sandbox execution mechanism due to unsafe handling of the PATH environment variable. CVE-2026-25157 describes remote code execution through SSH command injection. Beyond those CVEs, OpenClaw’s own security materials also warn that safeBins is not a generic allowlist and that interpreters or runtime binaries should not be trusted casually, because that can undermine approval and execution controls. In other words, once shell execution or remote command paths are exposed, weak validation can turn agent mistakes into system-level compromise.

The fourth category is file disclosure, path handling, and data exfiltration. Public advisories have shown that MEDIA: directives could cause OpenClaw to stage and send arbitrary local files that were readable by the OpenClaw process. Another advisory explains that a malicious or compromised MCP tool server could exfiltrate arbitrary local files by injecting MEDIA: directives into tool result text. Additional file-handling advisories have described sensitive-file disclosure through attachment-path metadata and similar staging paths. These cases matter because they show that file access is not a secondary feature in an AI agent; it is a high-impact privilege boundary. Once that boundary is crossed, the likely outcome is not merely inconvenience, but leakage of secrets, chat history, documents, credentials, or other sensitive local data.

The fifth category involves webhooks, remote fetching, and plugin or skill supply-chain risk. Public advisories show that Telegram webhook configurations could accept forged updates when secrets were not correctly validated, while the optional BlueBubbles plugin had webhook authentication weaknesses, including a passwordless fallback path or trust assumptions based on loopback/proxy conditions. OpenClaw advisories have also documented SSRF-style issues in image or attachment fetching, media URL hydration, citation redirect resolution, and redirect-chain validation for allowlisted media targets. On top of that, CNCERT specifically warned that multiple OpenClaw-compatible skills had already been identified as malicious or potentially dangerous, with the ability to steal keys or install backdoors. This is a reminder that external integration points do not merely extend functionality; they also import risk directly into the agent’s core trust boundary.

Taken together, these disclosures support a clear risk conclusion. The five most dangerous deployment mistakes are: running OpenClaw as a shared system for users who do not fully trust one another, exposing the management or control interface to the public internet, installing untrusted skills, granting the agent excessive host privileges, and storing API keys or secrets in plaintext. This conclusion aligns closely with OpenClaw’s own security guidance and with CNCERT’s public warning.

From a practical defense standpoint, the mitigation priorities are also clear. First, upgrade to the latest patched release and keep monitoring the OpenClaw security advisory feed. Second, do not expose the web interface or management ports directly to the internet; OpenClaw’s official guidance states that the web interface is intended for local use only. Third, enforce least privilege and isolate the runtime in a container or virtual machine instead of running it broadly on a privileged host account. Fourth, do not allow mutually untrusted users to share a single gateway; separate trust boundaries should mean separate gateways, and ideally separate OS users or hosts. Fifth, tightly control skill sources, prefer only trusted and auditable plugins, and disable or limit risky update paths where appropriate. Finally, use the built-in openclaw security audit tooling, which is specifically designed to detect dangerous configuration flags, insecure trust-proxy setups, safeBins mistakes, and other common security foot-guns.


OpenClaw – A Complete Clean Reinstall of OpenClaw and Telegram Bot Reset Guide

A Complete Clean Reinstall of OpenClaw and Telegram Bot Reset Guide

First, remove OpenClaw completely together with its service, state directory, and workspace, then delete the old Telegram bot, and finally reinstall everything and create a brand-new bot.

OpenClaw already provides a built-in uninstall flow. The openclaw uninstall command removes the gateway service and local data. If you want the removal to be as thorough as possible, the official documentation also recommends deleting the state directory, the workspace, and removing the CLI itself according to the way you originally installed it.

1. Completely Remove “OpenClaw”

The most recommended way to do a clean reinstall

Start with:

openclaw uninstall --all --yes --non-interactive

This is the official non-interactive full uninstall command. It removes the service, state, workspace, and related local content. However, whether the CLI executable itself is still present depends on how you originally installed it.

Then remove the CLI as well:

npm rm -g openclaw

If you installed it with pnpm or bun instead of npm, use one of these instead:

pnpm remove -g openclaw
# or
bun remove -g openclaw

The OpenClaw documentation is very clear on this point: the standard installation from install.sh or install.ps1 uses a global npm installation by default, so the corresponding uninstall command is npm rm -g openclaw.

If you want to manually verify that everything is gone

You can also check and remove these paths manually:


echo "$HOME"
echo "$OPENCLAW_STATE_DIR"
Common result:
HOME prints something like /Users/yourname or /home/yourname
OPENCLAW_STATE_DIR is blank
That is normal. In that case, the command will delete:
~/.openclaw
So you can also run this directly:
rm -rf ~/.openclaw 

rm -rf "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}" rm -rf ~/.openclaw/workspace 

According to the OpenClaw documentation, the default state directory is ~/.openclaw, and the default workspace is ~/.openclaw/workspace. Sessions, configuration, credentials, logs, and other data are also stored under this state directory.

If you previously used profiles, remove those profile directories too:

rm -rf ~/.openclaw-*

The official documentation states that profiles are stored by default under paths like ~/.openclaw-<profile>.

If you are on macOS, make sure no background service is left behind

If the openclaw command is already gone but the background service is still running, the official manual cleanup commands for launchd are:

UID means your user ID on macOS or Linux.

echo $UID

launchctl bootout gui/$UID/ai.openclaw.gateway
rm -f ~/Library/LaunchAgents/ai.openclaw.gateway.plist

These are the default macOS service label and plist location.

If you installed the Mac app, you can also remove it with:

rm -rf /Applications/OpenClaw.app

This is also listed separately in the official uninstall steps.

If you originally ran it from a git clone

In that case, first uninstall the service, then delete the repository directory directly. The official guidance for a source checkout is: uninstall the service first, then remove the repo, and then remove the state directory and workspace.

2. Delete the Old Telegram Bot and Create a New One

If you suspect the old bot is problematic, that is a reasonable approach. Telegram’s official BotFather supports the following commands:

  • /newbot: create a new bot
    • name -> username
    • /token -> username
  • /token: generate a new token for an existing bot
  • /deletebot: permanently delete the old bot; the username will be released, and the action is irreversible
    • username -> Yes, I am totally sure.

Steps to create a new bot

Go to @BotFather in Telegram and run:

/newbot

BotFather will ask for two things:

  • Bot name: the display name, which can be anything
  • Bot username: must be 5–32 characters, can only contain Latin letters, numbers, and underscores, and must end in bot, for example my_openclaw_bot

The username cannot be changed later. Once creation succeeds, BotFather will give you a token.

If you want to completely retire the old bot, run this in BotFather:

/deletebot

If you only suspect the token was leaked but want to keep the same bot, run:

/token

This will generate a new token.


3. Reinstall a Fresh Copy of OpenClaw

The officially recommended installation command is:

curl -fsSL https://openclaw.ai/install.sh | bash

This installer automatically checks your system, installs the required Node version, and installs OpenClaw. Node 24 is the recommended version, while Node 22.16+ is also supported.

After installation, the onboarding flow recommended in the official FAQ is:

openclaw onboard --install-daemon

This installs the daemon or service as part of the setup.

DuckDuckGo Search.

The official OpenClaw documentation clearly states that DuckDuckGo Search does not require an API key or an account. However, it also notes that this is an experimental, unofficial integration, so it may occasionally break due to page changes or anti-bot protections. The official recommendation is to prefer an API-backed provider such as Brave for production use.

Skip web search for now and configure it later.

The OpenClaw onboarding documentation states that the web search step can be skipped, and you can configure it later with:

openclaw configure --section web

4. Connect the New Bot Back to OpenClaw

The official OpenClaw configuration method for Telegram is to put the token into the configuration or environment variables, then start the gateway. Telegram does not use openclaw channels login telegram.

The simplest base configuration looks like this:

{
"channels": {
"telegram": {
"enabled": true,
"botToken": "123456:ABC...",
"dmPolicy": "pairing",
"groups": {
"*": { "requireMention": true }
}
}
}
}

This is the minimal working example from the official documentation.

You can also do it through the CLI:

openclaw channels add --channel telegram --account default --name "My Telegram Bot" --token 'your-new-token'

The OpenClaw CLI reference includes an example using channels add --channel telegram ... --token ....

Then start the gateway and pair the bot:

bot -> /start -> pairing code

openclaw gateway
openclaw pairing list telegram
openclaw pairing approve telegram <pairing-code>

The default Telegram DM policy is pairing. After the first private chat, you need to approve the pairing code, and the code expires after 1 hour.

5. If You Want the Bot to Work in Groups, Do These Too

If you want the new bot to work properly in group chats, both Telegram’s official guidance and the OpenClaw documentation highlight two important things:

Allow the bot to be added to groups

In BotFather, enable:

/setjoingroups

choose a bot -> enable

Make sure the bot can see group messages

Bots have Privacy Mode enabled by default. If you want the bot to see ordinary group messages, you have two options:

  • turn off privacy mode with /setprivacy -> Disable, or
  • make the bot a group administrator directly (*)

After changing privacy mode, remove the bot from the group and add it back again. Telegram only applies the new setting after the bot is re-added.

If you only want the bot to respond when someone mentions @bot, you can keep Privacy Mode enabled and set requireMention: true in the configuration. That is also the default example shown in the OpenClaw documentation.

vi ~/.openclaw/openclaw.json

@userinfobot -> /start

ID: 12345

{

  "commands": {

    "allowFrom": {

      "telegram": ["user id", "user id 2"]

    }

  },

  "channels": {

    "telegram": {

      "name": "My Telegram Bot",

      "enabled": true,

      "dmPolicy": "allowlist",

      "allowFrom": ["user id", "user id 2"],

      "botToken": "BotFather token",

      "groupPolicy": "open",

      "groupAllowFrom": ["user id", "user id 2"],

      "groups": {

        "*": {

          "requireMention": false

        }

      },

      "streaming": "partial"

    }

  }

}

 

 

March 22, 2026

Film Simulations for Fujifilm RAW Files

How to Turn Fujifilm RAW Files into Different Film Simulations

When you save a Fujifilm photo as RAW, the important thing is that the RAW file keeps the underlying sensor data, and Fujifilm’s manuals say RAW conversion creates a new rendered copy while leaving the original RAW data unchanged. That is why one RAF file can later be turned into different looks, including different film simulations, after the photo has already been taken.

1. FUJIFILM X RAW STUDIO

Cost: Free.
Status: Official Fujifilm method.
How close is it to the “real” Fujifilm film simulation? Closest desktop method, because the camera itself does the processing.

If you want the desktop workflow that stays closest to true Fujifilm rendering, FUJIFILM X RAW STUDIO is the strongest option. Fujifilm says the software is a free download, and that it uses the image processor inside the connected camera rather than the computer’s CPU. Fujifilm also says this preserves the camera’s tonality, color reproduction, and noise reduction. In practical terms, that means this is not just a “Fuji-like preset” on a computer; it is the camera doing the RAW development while the computer app acts as the interface.

It is processed through the camera’s own image processor rather than by a fully independent desktop RAW engine, and the camera must be connected to the computer via USB. Fujifilm’s guide says you must put the camera into USB RAW CONVERSION mode, connect it, turn it on, and then launch X RAW STUDIO. It also says RAW conversion only works when the connected camera matches the model that shot the RAW file, so an X-T2-connected workflow is for X-T2 RAW files, an X-T5-connected workflow is for X-T5 RAW files, and so on.

The workflow is straightforward. First install X RAW STUDIO. Then connect a compatible Fujifilm camera by USB, set the camera to USB RAW CONVERSION mode, and turn the camera on. In the software, confirm the connected camera model, choose the source folder on your computer, select the RAW image, adjust the settings in the Conversion Settings pane, and then convert one file or a batch of files. Fujifilm says the converted JPEG or TIFF files are saved in the same folder as the original RAW files.

There are a few limitations. The RAW files have to be stored on the computer, the camera must remain connected during conversion, and Fujifilm notes that the process uses the camera battery, so charge matters. The key takeaway is simple: if your goal is the most faithful desktop version of Fujifilm’s own rendering pipeline, X RAW STUDIO is the best answer.

Can I use an X-T5 RAW file while connecting an X-T3, X-T4, or a future X-T6 to X RAW STUDIO?

No. Under Fujifilm’s official compatibility rule for X RAW STUDIO, the connected camera model must match the camera model that created the RAW file. Fujifilm explains this very clearly: an X-T2-connected workflow is for X-T2 RAW files, and the “compatible RAW files only” filter means that the software will only show RAW files that were shot by the same model as the currently connected camera. So in your example, X-T5 RAW + X-T5 connected works, but X-T5 RAW + X-T3 connected does not work, and X-T5 RAW + X-T4 connected does not work either. On the other hand, X-T5 RAW + another X-T5 body should work, because Fujifilm’s rule is based on the same camera model, not the same individual serial-numbered unit. As for a future X-T6, based on Fujifilm’s currently published rule, you should assume no unless Fujifilm officially changes the compatibility policy or explicitly states that cross-model processing is supported. Right now, the rule is still “same model RAW only,” not “a newer model can process older model RAW files.” The underlying reason is simple: X RAW STUDIO does not decode the RAW file on the computer by itself; it sends the job to the image processor inside the camera that is currently connected, and therefore compatibility is tied to the connected camera model. The simplest way to remember it is: in X RAW STUDIO, use the same camera model as the one that created the RAW file.

2. Capture One / Fujifilm RAW Converter

Cost: Capture One Pro is paid; free trial available. Fujifilm RAW Converter is an official free or complimentary Fujifilm-specific option, but with limitations.
Status: Officially supported Fujifilm-related workflow.
How close is it to the “real” Fujifilm film simulation? Supported, but not the same as Fujifilm’s own camera/X RAW STUDIO processing pipeline.

Capture One does support Fujifilm Film Simulations for supported RAF files. Capture One’s official documentation says you can choose them from the Curve dropdown in the Base Characteristics tool, and that if Auto is selected, Capture One will apply the corresponding Fujifilm style from the camera when possible. So yes, Capture One can work with Fujifilm film simulation looks in a meaningful way.

But this is the important distinction. Capture One is not the same thing as true Fujifilm camera-side RAW conversion. Capture One’s own documentation explains that, after de-mosaicing the RAW file, Capture One applies its own ICC color profile and tone curve system, and its Fujifilm Film Simulation styles are implemented inside that Base Characteristics/ICC workflow. So Capture One is not literally “the real Fujifilm camera doing the conversion”; it is Capture One interpreting Fujifilm RAF files with official Fujifilm film-simulation support.

The old permanently free route many Fujifilm users remember—Capture One Express Fujifilm—has been discontinued, and Capture One says all Express license keys were disabled after February 12, 2024. So that old free path is gone.

What still exists officially is Fujifilm RAW Converter, which Fujifilm’s own site describes as free software exclusively available for Fujifilm users with basic editing tools, Fujifilm Film Simulations, and JPEG/TIFF export. However, Capture One’s own support page describes the license more narrowly, saying it is available to people who accessed the Capture One All in One Bundle offer for Fujifilm users and did not extend the subscription. So the careful conclusion is this: there is still an official free/complimentary Fujifilm-specific Capture One-based option, but you should not assume that buying any Fujifilm camera automatically gives you full Capture One Pro for free.

3. Converting the RAW File Directly in the Camera

Cost: Free after you own the camera.
Status: Official Fujifilm method.
How close is it to the “real” Fujifilm film simulation? It is the real in-camera Fujifilm method.

If you want the simplest and most direct method, you can convert the RAW file inside the camera itself. Fujifilm’s manuals say that you can display a RAW photo in playback, open RAW CONVERSION, and create a new rendered copy while leaving the original RAW data untouched. On supported cameras, Fujifilm also notes that these options can be opened quickly with the Q button during playback.

This is the most literal way to apply a different Fujifilm film simulation after the shot, because the conversion is happening in the camera’s own system. Depending on the model, Fujifilm lists options such as Film Simulation, white balance, WB shift, push/pull processing, dynamic range, grain effect, highlight tone, shadow tone, and other image parameters. That makes it easy to try multiple looks from the same RAW file without touching the original RAF.

The step-by-step flow is very simple: play back the RAW image, enter RAW CONVERSION, choose the settings you want, preview the result, and save the new JPEG or other rendered copy supported by your camera. This is the best choice when you want a quick result, no computer, and the genuine in-camera Fujifilm film simulation behavior.

4. RAW FILE CONVERTER EX powered by SILKYPIX

Cost: Free download.
Status: Officially distributed by Fujifilm, but powered by SILKYPIX.
How close is it to the “real” Fujifilm film simulation? Officially supported and film-simulation-aware, but not the same thing as the camera/X RAW STUDIO processor path.

There is another official desktop route that people often forget: RAW FILE CONVERTER EX powered by SILKYPIX. Fujifilm’s software page says it is dedicated RAW development software for RAF files, that it supports Fujifilm’s unique Film Simulation, and that it is available as a download from Fujifilm’s site. So this is officially supported by Fujifilm and it is free.

At the same time, Fujifilm is explicit in the name: it is powered by SILKYPIX. That means it is not the same as Fujifilm’s own camera-side processing engine. So this should be labeled clearly as you requested: official Fujifilm-supported, but third-party-powered desktop software rather than the actual in-camera/X RAW STUDIO pipeline.

The workflow is similar to normal desktop RAW editing. Download the program from Fujifilm, open the RAF file, choose a Film Simulation or one of the built-in “Tastes/Parameters,” fine-tune with sliders such as brightness, white balance, contrast, clarity, HDR, and spotting tools, and then export the final image. It is a valid option if you want a free desktop editor with official Fujifilm support, but you should expect it to be its own software rendering path rather than a mirror of the camera processor.

5. Lightroom / Adobe Camera Raw

Lightroom and Adobe Camera Raw are the last option to mention here: they use Adobe’s Camera Matching / Camera Settings profiles on supported files to approximate the camera look, but this is Adobe’s own RAW pipeline rather than Fujifilm’s camera-side conversion.

6. Are the results from FUJIFILM X RAW STUDIO, in-camera adjustment, and shooting with a film simulation selected in-camera the same?

In general, you can think of it this way: if you use the same Fujifilm camera, the same RAW file, and the same settings, then the film simulation result produced by FUJIFILM X RAW STUDIO and the result produced by the in-camera RAW conversion should, in principle, be the same. That is because Fujifilm officially explains that X RAW STUDIO essentially uses the camera’s own image processing engine to process RAW files, and the in-camera RAW conversion works on the same basis. Fujifilm also explains that with in-camera RAW conversion, you can repeatedly choose different film simulations for the same RAW file and generate different JPEGs. As for a JPEG that was produced at the moment of shooting with a film simulation selected in-camera, it will usually be the same, or almost the same, as the JPEG you create later from the RAW file in-camera or through X RAW STUDIO, as long as every setting is matched exactly. Fujifilm even provides a “Reflect Shooting Conditions” option in in-camera RAW conversion so that the JPEG can be generated according to the original shooting settings, and settings such as Color Chrome and Grain Effect are officially described as things that can be applied both at the time of shooting and later during RAW conversion, whether in-camera or in X RAW STUDIO. In real use, however, people often see differences, and that is usually because of three main reasons. First, the settings are not actually aligned: it is not enough for only the film simulation name to match; white balance, WB shift, dynamic range, highlight, shadow, color, sharpness, grain, Color Chrome, Color Chrome FX Blue, clarity, and similar parameters also need to match, otherwise the look will change. Second, there may be no RAW file available: if you shot JPEG only, then later you cannot truly redo the Fujifilm RAW conversion process, and you can only make limited edits to an already rendered JPEG. Third, the camera model or firmware may differ: X RAW STUDIO depends on the connected camera to do the processing, so different models, processors, and firmware versions can differ in supported film simulations and image processing behavior. So the most practical conclusion is: if you still have the RAW file, then X RAW STUDIO and in-camera RAW conversion should match; and a JPEG produced at shooting time should also match or be nearly identical if all settings are exactly the same. The biggest source of differences is usually not the method, but unmatched settings or the absence of the RAW file.

7. 

If your priority is the most “real Fujifilm” desktop result, use FUJIFILM X RAW STUDIO; if you want the fastest no-computer workflow, use in-camera RAW conversion; if you want a broader editing environment and accept that it is not the literal Fujifilm processor path, use Capture One or Fujifilm RAW Converter; and if you want another free official Fujifilm-supported desktop option that is third-party-powered, RAW FILE CONVERTER EX powered by SILKYPIX is worth knowing about.

MCP Prompts

 

How to Use MCP Prompts

In the Model Context Protocol (MCP), a prompt is a named, reusable, parameterized template that an MCP server exposes to a client. MCP defines three core server-side primitives: prompts, resources, and tools. Prompts help structure model interactions, resources provide context data, and tools let the model perform actions such as API calls or computations. MCP itself uses JSON-RPC 2.0 for these interactions.

The most important idea is this: an MCP prompt is not the same thing as “some text you send to the model.” In MCP, a prompt is a discoverable protocol object. The client can list available prompts, retrieve one by name, and pass arguments into it. The server then returns a structured set of messages for the client to use. In other words, MCP prompts are closer to workflow templates than to ad hoc strings.

Another important distinction is control flow. MCP prompts are designed to be user-controlled: users are expected to explicitly choose them, often through UI elements such as slash commands or menu items. By contrast, MCP tools are designed to be model-controlled: the model can discover and invoke them automatically when appropriate, with the client ideally keeping a human in the loop for safety.

The basic API shape

At initialization, a server declares which capabilities it supports. For prompts, it declares prompts; for argument suggestions, completions; for executable functions, tools. MCP also supports notifications such as notifications/prompts/list_changed and notifications/tools/list_changed when those lists change.

A simplified capability declaration looks like this:

{
"capabilities": {
"prompts": { "listChanged": true },
"completions": {},
"tools": { "listChanged": true }
}
}

For prompts, the core requests are prompts/list and prompts/get. The first discovers what exists; the second retrieves one prompt and fills in its arguments. MCP also provides completion/complete so the server can suggest argument values while the user is typing.

Here is a simplified prompt flow:

// 1) Discover prompts
{
"jsonrpc": "2.0",
"id": 1,
"method": "prompts/list"
}
// 2) Example response
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"prompts": [
{
"name": "incident_triage",
"title": "Triage an Incident",
"description": "Guide the model through production incident analysis",
"arguments": [
{ "name": "service", "required": true },
{ "name": "severity", "required": true }
]
}
]
}
}
// 3) Retrieve one prompt with arguments
{
"jsonrpc": "2.0",
"id": 2,
"method": "prompts/get",
"params": {
"name": "incident_triage",
"arguments": {
"service": "payments",
"severity": "high"
}
}
}
// 4) Example response
{
"jsonrpc": "2.0",
"id": 2,
"result": {
"description": "Prompt for incident triage",
"messages": [
{
"role": "assistant",
"content": {
"type": "text",
"text": "You are helping investigate a production incident. Be concise and evidence-driven."
}
},
{
"role": "user",
"content": {
"type": "text",
"text": "Investigate the payments service. Severity is high."
}
}
]
}
}

And if the client wants autocomplete while the user enters arguments:

{
"jsonrpc": "2.0",
"id": 3,
"method": "completion/complete",
"params": {
"ref": {
"type": "ref/prompt",
"name": "incident_triage"
},
"argument": {
"name": "service",
"value": "pay"
}
}
}

The key thing to notice is that the prompt API stops at retrieval. MCP defines prompts/list and prompts/get, but not prompts/call. Execution belongs to tools, which are invoked through tools/call. That is the clearest protocol-level difference between a prompt and a tool.

What comes back from prompts/get?

What you get back is a messages array. Those messages can contain text, image, audio, or embedded resources. The roles inside prompt messages are user or assistant, which makes prompts suitable for plain instructions, few-shot examples, multimodal guidance, or templates that bundle instructions together with server-managed reference material.

That means a retrieved prompt can do several useful things. It can give the model a repeatable instruction pattern, provide examples of the style or structure you want, include domain context directly inside the prompt payload, and standardize how users start common workflows. A client can also expose these prompts as slash commands or other UI actions, since the protocol is designed for discoverability but does not force a specific interface.

Just as importantly, MCP does not dictate exactly how an AI application must use the returned prompt with its own LLM pipeline. The architecture docs explicitly say MCP focuses on context exchange and does not dictate how AI applications use LLMs or manage the context they receive. So the client may insert the returned messages directly into the conversation, show them to the user first, combine them with other context, or feed them into a larger orchestration flow.

A concrete example

Imagine an MCP server for developer operations. It exposes:

  • a prompt called incident_triage
  • a resource containing the service runbook
  • tools such as fetch_logs, check_deployments, and create_ticket

The user selects “Triage an Incident” from the UI, enters service=payments and severity=high, and the client calls prompts/get. The server returns structured messages such as: investigate carefully, use evidence, summarize likely causes, and include next steps. It may also embed the runbook as a resource inside the prompt. Then the model starts reasoning over that prompt and, if needed, calls tools like fetch_logs or check_deployments. This is very close to the pattern described in the MCP docs: a server can expose tools, a resource, and a prompt that demonstrates or structures how those tools should be used together.

That is why a prompt is so useful: it can encode how to begin a workflow, while tools provide what actions are available inside that workflow. The prompt gives the model a playbook; the tools give it hands and eyes.

What kinds of scenarios are prompts good for?

Prompts are especially good for repeatable, structured, user-initiated workflows. Good examples include code review, weekly report generation, travel planning, drafting standard documents, guided analysis, and domain-specific assistants where you want the user to start from a known template instead of free-form chatting. MCP’s own docs describe prompts as reusable templates, and the official blog shows them being used for workflow automation such as meal planning.

They are also useful when argument entry should feel polished. Since MCP supports completion/complete, the server can suggest valid values while the user types. That makes prompts feel more like a command palette or IDE action than a plain text box.

Prompts are less compelling when the task is highly open-ended and the model can already decide what to do from the user’s plain language request. In those cases, tools alone may be enough. But when you want consistency, discoverability, parameterization, and workflow guidance, prompts are a strong fit. That is exactly the niche they occupy in MCP.

What is the relationship between prompts and tools?

The cleanest way to think about it is:

Prompt = guidance and structure
Tool = execution and side effects

A prompt tells the model how to approach a task. A tool lets the model fetch data, compute something, or change something in the outside world. At the protocol level, prompts are listed and retrieved; tools are listed and called. Tools also define an inputSchema, may define an outputSchema, and return results through content and optionally structuredContent.

So a prompt is not a weaker version of a tool, and a tool is not a better version of a prompt. They solve different problems. Prompts help with intent framing, workflow standardization, and UX discoverability. Tools help with real actions, fresh data, and system integration. In a mature MCP app, you usually want both.

Should you use the prompt first, the tool first, or both?

MCP does not require one universal order. The protocol separates capabilities, but leaves orchestration decisions to the client application. In practice, there are four common patterns.

1. Prompt first, then tools
This is the most common guided-workflow pattern. The user explicitly selects a prompt, the client retrieves its messages, and then the model may call tools while following that template. This fits things like code review, incident response, or travel planning. It matches the “user-controlled prompt, model-controlled tool” design very well.

2. Tools only
This works when the model already understands the task from normal conversation and just needs capabilities. For example, if the user says “check the weather in Tokyo,” the model may only need a weather tool. No prompt template is necessary.

3. Prompt plus resources, with no tool call
Sometimes the goal is pure generation or analysis, not action. In that case a prompt can include embedded resources and ask the model to produce an answer without calling any tools.

4. Tool first, then a client-constructed prompt
This is also possible, but it is more of an application design choice than a special MCP prompt pattern. Since MCP does not dictate how clients manage LLM context, a client can fetch some data through tools or resources and then compose its own downstream prompting strategy.

My practical recommendation is simple: use prompts first when you want a reusable, guided entry point for a workflow; use tools first when the task is ad hoc and action-oriented; use both together when you want the best user experience and the strongest execution capability.

Summary

MCP prompts are discoverable, parameterized templates exposed by a server. You find them with prompts/list, fetch them with prompts/get, and optionally support user-friendly argument entry with completion/complete. The result is a structured messages payload that can contain text, examples, multimodal content, and embedded resources.

What retrieved prompts can do is shape the model’s behavior in a repeatable way: they can start workflows, standardize outputs, carry domain context, and make advanced flows easy for users to launch from a UI. But they do not execute actions by themselves, because MCP execution belongs to tools through tools/call.

So the short mental model is: prompts tell the model how to work; tools let the model do work. In real MCP systems, prompts and tools are complementary, not competing features. The best systems usually use prompts to give structure and tools to provide power.