Skip to content

Tutorial: Visualizations with the MCP Server

In this tutorial you'll configure the Panel Live Server MCP server so that an AI assistant can create interactive visualizations on your behalf using natural language. By the end, you'll have asked an AI to produce a chart and seen it rendered live in your IDE.

What You'll Need

  • Panel Live Server installed, see Installation
  • Familiarity with snippets and execution methods, see Standalone Server
  • An MCP-compatible AI assistant: Claude Code, Claude Desktop, GitHub Copilot (VS Code), or similar

Step 1: Add Panel Live Server to your MCP configuration

See Installation → Connect to your MCP client for the full setup instructions for VS Code, Cursor, Claude Desktop, Claude Code, and claude.ai.

Note

When the MCP server starts, it automatically starts the Panel server in the background. You do not need to run pls serve separately. A standalone pls serve launched from the same environment resolves to the same per-environment port, so it shares that server rather than colliding. Run pls status to see the address.

Step 2: Verify the connection

Ask your AI assistant:

List your available MCP tools.

You should see four tools in the response:

  • show: validates the code, renders the visualization, and returns a live URL
  • screenshot: takes a picture of a visualization for the AI to look at — either a draft it has not shown you yet, so it can check its own work first, or one you already have, so it can answer questions about how it looks. It captures one screen exactly as loaded by default, and says when there is more — what else is on the page and whether content continues past the fold — so the AI can ask for the rest of a scrolling page, or click/select/drag its way to a particular state, only when the question needs it
  • edit: changes part of a snippet without resending all of it. Asking for a different colour costs the AI one line instead of the whole chart
  • evaluate: runs code and hands back its text output — what it printed and the value of its last line. No browser, no picture. This is how the AI checks a fact ("does this option exist?", "what columns does that have?") without rendering anything

They differ by who receives what: show gives you a live page, while screenshot, edit, and evaluate all report back to the AI.

Step 3: Create your first AI-assisted visualization

Download the Palmer Penguins dataset and save it as penguins.csv. Then ask your AI:

My dataset is penguins.csv. Show the distribution of the 'species' column as an interactive bar chart. Use the show tool.

Your AI will call show, which validates the code and then renders it in one step. You'll see a response like:

Visualization created successfully!
View at: http://localhost:5077/view?id=...

Click the URL (or the inline MCP App panel if your client supports it) to see the chart.

Note

Inline preview support depends on the MCP client. Some clients permit the embedded iframe, while others block localhost origins and require opening the visualization in your browser.

Prompting tips

Mentioning the show tool explicitly ("use the show tool") ensures the AI uses it rather than describing the code. In VS Code you can reference it as #show.

Step 4: Explore relationships

Continue the conversation:

Show me a scatter plot of 'flipper_length_mm' vs 'body_mass_g', colored by species.

The AI will produce a new visualization with a color-coded scatter plot, interactive tooltips, zoom, and pan.

Step 5: Ask a follow-up question about how it looks

Now ask something that can only be answered by looking at the chart, not by reading the code:

Which species has the widest spread of body mass in that scatter plot?

The AI cannot open a browser, so to answer correctly it calls screenshot on the snippet it just created, gets back a picture of the rendered chart, and reads the answer off the image.

Why this matters

Plots are not the same as the raw data: heatmaps can flip row order, axes get inverted, categories get sorted, and histograms bin values. Reasoning from the code alone often gives a different answer than what the chart actually shows. screenshot lets the AI check the real rendered output instead of guessing.

Step 6: Build an interactive dashboard

Ask the AI to create a full Panel application:

Create an interactive dashboard for the penguins dataset with a dropdown to filter by species and an island selector. Show a scatter plot that updates when the filters change.

The AI will use the server execution method and produce a reactive Panel app with widgets. The dashboard updates in real time as you interact with it.

Step 7: Iterate

If the result isn't what you expected, continue the conversation:

  • "Color the points by island instead"
  • "Add a trend line"
  • "Show only penguins with body mass greater than 4000g"
  • "Display the scatter plot and a histogram side by side"

Each message produces a new visualization, and the previous ones stay accessible at their URLs — so "actually, go back to the earlier one" costs nothing.

For a small change, the AI does not resend the whole chart. It calls edit with just the part that differs, which forks a new version and leaves the one you are looking at untouched until the new one is ready. You will see a fresh entry appear in your feed rather than the existing chart changing under you. On a long snippet this is the difference between a one-line message and a two-hundred-line one.

Step 8: Check what packages are available

The AI cannot install packages itself, and is instructed to prefer HoloViz packages (hvPlot, HoloViews, Panel) and fall back to other well-known libraries only when needed — so you rarely have to think about this. To inspect the environment yourself, use the pls list packages CLI command in a terminal:

pls list packages          # list everything installed
pls list packages plotly   # filter by name

If a package you need is missing, see Installation for how to add it with --with.

How it works

A typical AI-assisted session looks like this:

  1. The AI calls show, which first validates the code (syntax, security, package availability, Panel extensions) and then sends it to the Panel server via the REST API
  2. The Panel server stores and executes the snippet, returning a URL
  3. The URL is shown to you, click it to open the live visualization
  4. If you ask a question about how the result looks, the AI calls screenshot to see it before answering
  5. If you ask for a small change, the AI calls edit with only the part that differs, then show on the version that comes back
  6. To check a fact rather than an appearance, the AI calls evaluate instead — it returns text, so no browser is launched and nothing is added to your feed

When the AI is building something from scratch it often works in private first: screenshot renders a draft and returns the picture to the AI alone, so it can fix its own mistakes before anything reaches your feed. Only the approved version gets shown to you.

See Architecture for the full picture.

Troubleshooting

show tool is not available

Verify the MCP server started successfully. Check your AI client's MCP server logs for startup errors. If pls is not on PATH inside the MCP process, use the full path:

{ "command": "/home/user/.local/bin/pls", "args": ["mcp"] }

Visualization shows an error

The error message is returned to the AI. Ask it to fix the issue, it has the full error context. Or start with a simpler snippet to confirm the server is working:

Show 1 + 1 using the show tool.

Claude Desktop Not Showing the Visualization

Claude Desktop and Cowork restrict which origins their iframes may load, and localhost is not among them, so neither can preview a visualization in the chat. Both show an Open in browser ↗ button instead. Click it, or open the returned http://localhost:5077/view?id=... URL yourself, and the visualization runs there with full interactivity against the live server.

If a client console logs an error like:

Framing 'http://localhost:5077/' violates the following Content Security Policy directive: "frame-src 'self' blob: data:".

then the visualization URL is valid and the host simply refused to frame it. Open it in your browser instead.

Package not found in server environment

The server runs in an isolated uv tool environment. Install missing packages as described in Installation.

screenshot fails with a Playwright error

The screenshot tool needs the Chromium browser that Playwright manages, which is not installed automatically. Install it once with:

pls install-browser

This downloads Chromium into the same environment that runs pls. See Installation → Enable the screenshot tool for the per-installer command.

What You've Learned

  • Configure the Panel Live Server MCP server for your AI assistant
  • Ask the AI to create visualizations using natural language
  • Ask a follow-up question about a visualization's appearance and have the AI check with screenshot
  • Iterate on visualizations through conversation, with small changes going through edit
  • Check available packages with the pls list packages CLI command

Next Steps