Add playground guide

Author: samuv

docs/toolhive/guides-ui/playground.mdx

@@ -0,0 +1,265 @@
+---
+title: Test MCP servers with Playground
+description:
+  Use the Playground feature to test and validate MCP servers directly in the
+  ToolHive UI with AI model providers.
+---
+
+import useBaseUrl from '@docusaurus/useBaseUrl';
+import ThemedImage from '@theme/ThemedImage';
+
+The Playground feature in ToolHive allows you to test and validate MCP servers
+directly within the UI, without requiring additional client setup. This
+streamlined testing environment helps teams quickly evaluate functionality and
+behavior before deploying MCP servers to production environments.
+
+<ThemedImage
+  alt='ToolHive Playground initial interface'
+  sources={{
+    light: useBaseUrl('/img/toolhive/toolhive-ui-playground-start-ligh.webp'),
+    dark: useBaseUrl('/img/toolhive/toolhive-ui-playground-start-dark.webp'),
+  }}
+  title='ToolHive Playground initial interface'
+/>
+
+## Key capabilities
+
+### Instant testing of MCP servers
+
+Enter an AI model API key, select your MCP servers and tools, and begin testing
+immediately—right inside the desktop app. The Playground eliminates the friction
+of setting up external AI clients just to validate that your MCP servers are
+working correctly.
+
+### Transparent audit logs
+
+See tool details, parameters, and execution results directly in the UI, ensuring
+full visibility into tool performance and responses. Every interaction is
+logged, making it easy to understand exactly what your MCP servers are doing and
+how they're responding to requests.
+
+### Integrated ToolHive management
+
+The Playground includes a dedicated MCP server for ToolHive itself, allowing you
+to manage your 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.
+
+## Getting started
+
+To start using the Playground feature:
+
+1. **Access the Playground**: Click the **Playground** tab in the ToolHive UI
+   navigation bar.
+
+2. **Configure API keys**: Click **Configure your API Keys** to set up access to
+   AI model providers.
+
+<ThemedImage
+  alt='ToolHive Playground API keys configuration'
+  sources={{
+    light: useBaseUrl(
+      '/img/toolhive/toolhive-ui-playground-api-keys-light.webp'
+    ),
+    dark: useBaseUrl('/img/toolhive/toolhive-ui-playground-api-keys-dark.webp'),
+  }}
+  title='API keys configuration modal'
+/>
+
+- **OpenAI**: Enter your OpenAI API key to use GPT models
+- **Anthropic**: Add your Anthropic API key for Claude models
+- **Google**: Configure Google AI API key for Gemini models
+- **xAI**: Set up xAI API key for Grok models
+- **OpenRouter**: Add OpenRouter API key for access to multiple model providers
+
+3. **Select MCP tools**: Click the tools icon to manage which MCP servers and
+   tools are available in the Playground.
+
+<ThemedImage
+  alt='ToolHive Playground tools management showing available MCP tools'
+  sources={{
+    light: useBaseUrl(
+      '/img/toolhive/toolhive-ui-playground-thv-mcp-light.webp'
+    ),
+    dark: useBaseUrl('/img/toolhive/toolhive-ui-playground-thv-mcp-dark.webp'),
+  }}
+  title='MCP tools management interface'
+/>
+
+- View all your running MCP servers
+- Enable or disable specific tools from each server
+- Search and filter tools by name or functionality
+- The `toolhive mcp` server is included by default, providing management
+  capabilities
+
+4. **Start testing**: Begin chatting with your chosen AI model. The model will
+   have access to all enabled MCP tools and can execute them based on your
+   requests.
+
+<ThemedImage
+  alt='ToolHive Playground chat interface with AI model and MCP tools'
+  sources={{
+    light: useBaseUrl(
+      '/img/toolhive/toolhive-ui-playground-start-chat-ligh.webp'
+    ),
+    dark: useBaseUrl(
+      '/img/toolhive/toolhive-ui-playground-start-chat-dark.webp'
+    ),
+  }}
+  title='Playground chat interface in action'
+/>
+
+## Using the Playground
+
+### Testing MCP server functionality
+
+The Playground is ideal for validating that your MCP servers work as expected:
+
+```text
+Can you list all my MCP servers and show their current status?
+```
+
+The AI will use the `list_servers` tool from the ToolHive MCP server to provide
+a comprehensive overview of your server status.
+
+<ThemedImage
+  alt='ToolHive Playground showing AI response with MCP tool execution results'
+  sources={{
+    light: useBaseUrl(
+      '/img/toolhive/toolhive-ui-playground-chat-response-light.webp'
+    ),
+    dark: useBaseUrl(
+      '/img/toolhive/toolhive-ui-playground-chat-response-dark.webp'
+    ),
+  }}
+  title='Chat response showing tool execution and results'
+/>
+
+```text
+Use the GitHub MCP server to search for recent issues in the microsoft/vscode repository
+```
+
+If you have the GitHub MCP server running, the AI will execute the appropriate
+GitHub API calls and return formatted results.
+
+### Managing servers through conversation
+
+The ToolHive desktop app automatically spins up a dedicated MCP server
+(`toolhive mcp`) that orchestrates ToolHive operations through natural language
+commands. This approach provides several key benefits:
+
+- **Unified interface**: Manage your MCP infrastructure using the same
+  conversational AI interface you use for testing
+- **Contextual operations**: The AI understands your current server state and
+  can make intelligent decisions about which servers to start, stop, or
+  troubleshoot
+- **Reduced complexity**: No need to switch between the chat interface and
+  traditional UI controls—everything can be done through conversation
+- **Audit trail**: All management operations are logged in the same transparent
+  way as tool executions, providing clear visibility into what actions were
+  taken
+
+Take advantage of these integrated ToolHive management tools:
+
+```text
+Start the fetch MCP server for me
+```
+
+```text
+Stop all unhealthy MCP servers
+```
+
+```text
+Show me the logs for the meta-mcp server
+```
+
+### Validating tool responses
+
+The Playground shows detailed information about each tool execution:
+
+- **Tool name and description**: What tool was called and its purpose
+- **Input parameters**: The exact parameters passed to the tool
+- **Execution status**: Whether the tool succeeded or failed
+- **Response data**: The complete response from the tool
+- **Timing information**: How long the tool took to execute
+
+This visibility helps you understand exactly how your MCP servers are behaving
+and identify any issues with tool implementation or configuration.
+
+## Best practices
+
+### API key security
+
+- Use dedicated API keys for testing that have appropriate rate limits
+- Regularly rotate API keys used in development environments
+- Consider using API keys with restricted permissions for testing purposes
+
+### Server management
+
+- Start only the MCP servers you need for testing to improve performance
+- Use the Playground to validate new server configurations before connecting
+  them to production AI clients
+- Test different combinations of tools to understand how they work together
+
+### Testing workflow
+
+1. **Isolated testing**: Test individual MCP servers one at a time to validate
+   their functionality
+2. **Integration testing**: Enable multiple servers to test how they work
+   together
+3. **Performance validation**: Monitor tool execution times and responses under
+   different loads
+4. **Error handling**: Intentionally trigger error conditions to validate proper
+   error handling
+
+## Troubleshooting
+
+### Common issues
+
+<details>
+<summary>API key not working</summary>
+
+If your API key isn't working:
+
+1. Verify the API key is correct and has proper permissions
+2. Check that you have sufficient quota or credits with the provider
+3. Ensure the API key hasn't expired or been revoked
+4. Try creating a new API key from the provider's dashboard
+
+</details>
+
+<details>
+<summary>MCP tools not appearing</summary>
+
+If your MCP server tools aren't showing up:
+
+1. Verify the MCP server is running (check the **MCP Servers** page)
+2. Click the tools icon and ensure the server's tools are enabled
+3. Try restarting the MCP server if it shows as unhealthy
+4. Check the server logs for any error messages
+
+</details>
+
+<details>
+<summary>Tool execution failing</summary>
+
+If tools are failing to execute:
+
+1. Check the tool's parameter requirements in the audit log
+2. Verify any required secrets or environment variables are configured
+3. Ensure the MCP server has necessary permissions (network access, file system
+   access)
+4. Review the server logs for detailed error information
+
+</details>
+
+## Next steps
+
+- Learn more about [client configuration](./client-configuration.mdx) to connect
+  ToolHive to external AI applications
+- Set up [secrets management](./secrets-management.md) for secure handling of
+  API keys and tokens
+- Explore [network isolation](./network-isolation.mdx) for enhanced security
+  when testing untrusted MCP servers
+- Check out the [registry](./registry.mdx) to discover new MCP servers to test
+  in the Playground

sidebars.ts

@@ -49,6 +49,7 @@ const sidebars: SidebarsConfig = {
         'toolhive/guides-ui/install',
         'toolhive/guides-ui/registry',
         'toolhive/guides-ui/run-mcp-servers',
+        'toolhive/guides-ui/playground',
         'toolhive/guides-ui/network-isolation',
         'toolhive/guides-ui/secrets-management',
         'toolhive/guides-ui/client-configuration',