Skip to content
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
111 changes: 111 additions & 0 deletions docs/toolhive/guides-ui/playground.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,16 @@ MCP servers directly through natural language commands. You can list servers,
check their status, start or stop them, and perform other management tasks using
conversational AI.

### Threaded conversations

Keep multiple chats organized in a sidebar with starred and recent groups. See
[Manage playground threads](#manage-playground-threads).

### Attachments

Send images and PDFs alongside your prompt. See
[Attach files to a message](#attach-files-to-a-message).

## Getting started

To start using the playground:
Expand Down Expand Up @@ -93,6 +103,14 @@ To start using the playground:
have access to all enabled MCP tools and can execute them based on your
requests.

5. **Manage chat threads**: See
[Manage playground threads](#manage-playground-threads) for sidebar, rename,
star, and delete actions.

6. **Attach images or PDFs**: See
[Attach files to a message](#attach-files-to-a-message) for supported types
and limits.

## Using the playground

### Testing MCP server functionality
Expand Down Expand Up @@ -173,6 +191,89 @@ The playground shows detailed information about each tool execution:
This visibility helps you understand exactly how your MCP servers are behaving
and identify any issues with tool implementation or configuration.

### Manage playground threads

The playground keeps each conversation in a separate thread so you can run
several testing sessions in parallel without losing context. Open the sidebar to
see your threads, with **Starred** entries pinned at the top and **Recents**
below. Untitled threads show as `New chat` until you give them a name.

Each row shows a relative timestamp such as `just now`, `5m ago`, `2h ago`, or
`3d ago`. Older threads show a short date instead.

To work with threads:

- **Start a new thread**: Click **New chat** at the top of the sidebar.
- **Rename a thread**: Double-click the thread row, or open its **Thread
options** menu and choose **Rename**. You can also click the title or the
pencil icon at the top of the chat to rename the active thread. The thread
row's tooltip confirms the double-click action:

> Double-click to rename

- **Star or unstar a thread**: Click the star icon next to the thread title, or
open **Thread options** and choose **Star** or **Unstar**. Starred threads
appear under **Starred** at the top of the sidebar.
- **Delete or unstar threads**: Open **Thread options** and choose **Delete** to
remove a thread you no longer need. The playground asks for confirmation:

> Delete "`<THREAD_NAME>`"? This cannot be undone.

Confirm with **Delete**, or back out with **Cancel**.

### Attach files to a message

Add images and PDFs to a message so the model can read them while it works with
your MCP tools. The composer accepts up to 5 files per message, each 10 MB or
smaller, and supports image files and PDFs.

To attach files:

1. Open the composer toolbar menu and choose **Add images or PDFs**, or drag
files onto the playground window. Drag-and-drop is enabled across the entire
playground.
2. Type your prompt and send the message. If you send a message that only
contains attachments, the playground records the message text as:

> Sent with attachments

In the chat history, the playground previews each attachment alongside the
message:

- **Images** appear inline. Click an image to open it in a larger modal preview.
- **PDFs** show as `📎 <FILE_NAME>` with a **Download** link so you can save the
original file.

If a file is rejected, the playground shows a toast that explains why:

- When you exceed the per-message limit:

> You reached the maximum number of files
>
> You can only upload up to 5 files

- When a file is over 10 MB:

> File size too large
>
> The file size must be less than 10MB

- When a file isn't an image or a PDF:

> File type not supported
>
> Only images and PDFs are supported

The composer placeholder reflects the playground state:

> Select an AI model to get started

is shown when no model is selected, then:

> Type your message...

once you've chosen one.

## Recommended practices

### Provider security
Expand Down Expand Up @@ -201,6 +302,16 @@ and identify any issues with tool implementation or configuration.
4. **Error handling**: Intentionally trigger error conditions to validate proper
error handling

### Thread and attachment hygiene

- Delete unused threads so the sidebar stays focused on the work you actually
return to.
- Star the conversations you want to keep close at hand. Otherwise they get
pushed down as new chats arrive in **Recents**.
- Attachments are sent to your AI provider. Strip credentials, customer
information, and other sensitive content from PDFs and screenshots before
sharing them.

## Next steps

- Learn about [client configuration](./client-configuration.mdx) to connect
Expand Down