Docker Labs: GenAI No. 20

Stop over-prompting! A smarter approach to MCP server design

The Model Context Protocol (MCP) provides us with both tool definitions and prompt definitions. But as an author of an MCP server, when do you need prompts?

Let's go through a simple example.

When we initially created an MCP server to generate QR codes, we thought the easiest path was to just expose the CLI interface of qrencode. The foundation models are familiar with the tool anyway, so they really didn't seem to need much additional prompting.

Here's the definition. (We obviously didn't work very hard on these descriptions.)

yaml
tools:
  - name: qrencode
    description: use the qrencode command
    parameters:
      type: object
      properties:
        args:
          type: string
          description: The arguments to pass to qrencode
    container:
      image: vonwig/qrencode:latest
      command:
        - "{{args}}"        

The problem with this definition is that the output of this command is not text.?It's an image.

So, how do we ingest this output in our clients??

Resources

MCP also supports resources. To turn image outputs into MCP resources, we decided to use the convention that any file written to /thread should be turned into a resource and returned to the client. However, the qrencode program itself doesn't know that it should write its output to /thread. It’s always up to the shell or environment to determine where to put the output, so we thought: Let's introduce a prompt.

> Run the qrencode command to generate a QR code and write it to /thread/qrcode.png

This did actually work. However, MCP server prompts are not very well supported across MCP clients today, and do we really need prompts anyway? Can we make this a tool-only approach? Why not just move the entire prompt to use the thread directly into the tool’s description?

Tool descriptions

We changed the above command description from "use the qrencode command" to "generate a QR code and write it to /thread/qrcode.png". That was actually much better. We didn't need a prompt but our MCP server started generating image resources for us.?You can try our new improvements to the QRencode tool yourself using our catalog.

Using the Chrome browser

We had also been using prompts to create workflows to automate web crawling using a headless Chrome browser. In this example, we gave the agent three tools.

1. the headless chrome browser itself
2. curl to locate the websocket for automating the browser
3. websocat for sending commands to the browser

The agent already knew a lot about using the Chrome devtools websocket. We didn't need to provide a lot of context.?However, our first set of tool descriptions for these were probably too simple. They were respectively.

1. start chrome browser
2. run a curl command
3. send a websocat message

With only these descriptions, we needed a prompt to describe how to use these tools together.?So we used a similar strategy and added context to the tool definitions.

1. Start the chrome browser in case it is not already running.
2. Run a curl command to get the websocket url and make sure that Chrome's websocket server is running. ALWAYS USE THIS TOOL FIRST. MAKE SURE TO USE THE CORRECT HOST HEADER AND ENDPOINT.
3. A tool to send and receive messages to headless Chrome via a websocket. Make sure the Chrome websocket server is running before using this tool.

With this update, we no longer need a prompt to set the context for how the tools should be used together. We can jump straight to the task we want to complete using the browser ("show me the docker.com home page with different color schemes: dark, rainbow, and 90s"). If you're like me, you'll also learn something about Chrome's devtools API. You can also find this MCP in our catalog.

And you won't need an MCP client that supports prompts.This should work with any mcp client you're currently using. For example, check out the recent Docker AI announcement.

Summary

We are working a lot harder on our tool descriptions, and even using AI to help us to author them. This is not to say that some prompts aren't worth sharing.?For example, this sqlite prompt?sets up a workflow involving sqlite and Claude artifacts, and it is really quite re-usable across?different topics.?It's a good example of a prompt that's useful to ship on its own.

Check out these two examples in our catalog, and as always, fall along in our public Github repo.