feat: Add comprehensive configuration examples and documentation #22
Conversation
- Add comprehensive MCP proxy setup for centralized server management - Include example configurations for proxy and Claude Desktop - Add startup script for easy proxy management - Provide detailed documentation and troubleshooting guide - Configure security features with tool filtering and auth tokens - Support for popular MCP servers: github, filesystem, puppeteer, memory, etc.
- Add examples directory with multiple configuration patterns - Include simple and comprehensive example configurations - Add Claude Desktop integration configuration example - Provide detailed documentation for all configuration options - Add startup script for easy testing of different configurations - Document security best practices and tool filtering - Include common MCP server installation and setup instructions This addition helps new users get started quickly while providing advanced configuration patterns for power users.
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hello @jlwainwright, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!
Summary of Changes
Hello team, gemini-code-assist here to provide a summary of this pull request. This PR, authored by jlwainwright, introduces comprehensive configuration examples and documentation for the MCP Proxy. The primary goal is to significantly lower the barrier to entry for new users, make it easier to integrate with tools like Claude Desktop, and demonstrate best practices for configuring MCP servers, including security features like tool filtering and using environment variables for sensitive data. It adds several new files, including example configuration files, detailed READMEs for setup and examples, and utility scripts for starting the proxy with different configurations.
Highlights
- New Configuration Examples: Adds
simple-example.jsonfor a minimal setup,comprehensive-example.jsonshowcasing all features and server types, andclaude-desktop-config.jsonfor easy Claude integration. - Updated Documentation: Includes a new
examples/README.mddetailing the configuration examples and a significantly revisedREADME.mdfocusing on this setup repository, covering quick start, configuration guide, security, management, and troubleshooting. - Utility Scripts: Adds
start-example.shto easily launch the proxy with different example configurations andstart-proxy.shfor a standard launch. - Security Best Practices: Examples and documentation demonstrate tool filtering (allow/block lists), using authentication tokens, restricting filesystem access to safe paths, and managing credentials via environment variables.
Changelog
Click here to see the changelog
- .gitignore
- Replaced the extensive, generated
.gitignorewith a simpler, more standard set of exclusions covering binaries, environment files, OS files, IDE files, logs, temp files, node modules, and Go-specific files. - Added comments suggesting exclusion of sensitive configuration files.
- Replaced the extensive, generated
- README-SETUP.md
- Added a new file providing a detailed, step-by-step guide for setting up the MCP Proxy specifically for Jacques' personal use with Claude Desktop, including architecture, quick start, configuration details, security features, management commands, troubleshooting, and benefits.
- README.md
- Transformed the README from a general guide for the
mcp-proxybinary into a guide for this specificmcp-proxy-setuprepository. - Added sections covering the purpose, architecture, quick start, included servers, detailed configuration guide (proxy settings, server types, tool filtering), security features, management, troubleshooting, resources, contributing, and acknowledgments.
- Included example JSON snippets for proxy and server configurations.
- Transformed the README from a general guide for the
- claude-config.example.json
- Added a new file providing an example JSON configuration for Claude Desktop to connect to the local MCP Proxy instance, specifying the proxy binary path and configuration file.
- examples/README.md
- Added a new file documenting the configuration examples found in the
examples/configsdirectory. - Describes each example file (
simple-example.json,comprehensive-example.json,claude-desktop-config.json) and their use cases. - Provides a detailed configuration guide covering basic structure, proxy settings, different server transport types (stdio, SSE, streamable-http), tool filtering, security best practices, environment variable usage, common server examples, and debugging tips.
- Added a new file documenting the configuration examples found in the
- examples/configs/claude-desktop-config.json
- Added a new file containing the example Claude Desktop configuration JSON, pointing to the proxy binary and its main configuration file (
config.json).
- Added a new file containing the example Claude Desktop configuration JSON, pointing to the proxy binary and its main configuration file (
- examples/configs/comprehensive-example.json
- Added a new file containing a detailed example of a comprehensive MCP Proxy configuration.
- Includes configurations for multiple servers (brave-search, github, filesystem, memory, puppeteer, git, sequential-thinking, remote-sse, streamable-http).
- Demonstrates various configuration options like
command,args,env,url,headers,timeout, andtoolFilterwithallowmode lists for each server.
- examples/configs/simple-example.json
- Added a new file containing a minimal example of an MCP Proxy configuration.
- Includes configurations for two basic servers (memory and filesystem) to provide a quick starting point.
- examples/start-example.sh
- Added a new executable bash script to simplify launching the MCP Proxy with different example configurations (
simple,comprehensive) or a custom one (custom). - Includes usage instructions, checks for the proxy binary, performs basic JSON validation on the selected config file, and starts the proxy with colored output.
- Added a new executable bash script to simplify launching the MCP Proxy with different example configurations (
- proxy-config.example.json
- Added a new file containing a detailed example of the main MCP Proxy configuration JSON.
- Includes settings for the proxy itself (
mcpProxy) and configurations for a wide range of MCP servers (mcpServers). - Demonstrates using
command,args,env(including environment variable substitution), andoptionswithtoolFilterfor various servers (brave-search, github, filesystem, puppeteer, memory, sequential-thinking, git, iterm, obsidian, browser-tools).
- start-proxy.sh
- Added a new simple executable bash script to start the MCP Proxy using the main
proxy-config.jsonfile, including basic status messages.
- Added a new simple executable bash script to start the MCP Proxy using the main
Using Gemini Code Assist
The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.
Invoking Gemini
You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.
| Feature | Command | Description |
|---|---|---|
| Code Review | /gemini review |
Performs a code review for the current pull request in its current state. |
| Pull Request Summary | /gemini summary |
Provides a summary of the current pull request in its current state. |
| Comment | @gemini-code-assist | Responds in comments when explicitly tagged, both in issue comments and review comments. |
| Help | /gemini help |
Displays a list of available commands. |
Customization
To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.
Limitations & Feedback
Gemini Code Assist is currently in preview and may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments to provide feedback.
You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.
Config files bloom,
JSON trees take root,
Proxy guides appear,
Making setup a treat.
Footnotes
-
Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩
There was a problem hiding this comment.
Code Review
This pull request introduces a wealth of documentation and example configurations, which is a fantastic step towards making MCP Proxy more accessible and easier to use. The new README.md, example JSON configuration files, and the examples/start-example.sh script are particularly valuable.
However, there are critical issues with README-SETUP.md and start-proxy.sh containing user-specific hardcoded information, which hinders their general applicability. Addressing these, along with a few other minor suggestions, will make this PR ready for merging.
Summary of Findings
- User-Specific Content in
README-SETUP.md: The fileREADME-SETUP.mdcontains multiple instances of user-specific information (references to "Jacques", hardcoded paths, a hardcoded token, and a future creation date). This makes the documentation misleading for general users. (Severity: high, commented) - Hardcoded Path in
start-proxy.sh: Thestart-proxy.shscript includes acdcommand to a hardcoded, user-specific absolute path, rendering it non-portable and unusable for others. (Severity: critical, commented) - OS-Specific Placeholder Paths in Example Configs: Example configuration files (
examples/configs/simple-example.json,proxy-config.example.json) use placeholder paths like/Users/username/Documentswhich are somewhat specific to Unix-like systems. More generic placeholders would improve clarity for users on all platforms. (Severity: medium, commented) - macOS-Specific Path in
README.md: The mainREADME.mdprovides a macOS-specific path for Claude Desktop configuration without explicitly stating its OS-specificity, which could confuse users on other platforms. (Severity: medium, commented) - Python Package Installation Method Consistency:
examples/README.mdsuggestspip installfor Python-based MCP servers, while the mainREADME.mdmentionsuv/uvx. Clarifying the recommended approach or mentioning both could be helpful. (Severity: low, not commented due to review settings) - Date Typo in
README-SETUP.md: TheREADME-SETUP.mdfile has a creation date ofMay 25, 2025, which is in the future. This is likely a typo and is part of the larger issue regarding this file's user-specific nature. (Severity: low, not commented due to review settings)
Merge Readiness
This pull request adds significant value with its new documentation and examples. However, due to the critical and high severity issues identified (specifically the user-specific hardcoding in README-SETUP.md and start-proxy.sh), I recommend that these changes not be merged until these issues are addressed. The medium severity issues should also be considered for improvement. I am not authorized to approve pull requests, but addressing these points will greatly improve the quality and general applicability of these contributions.
start-proxy.sh
Outdated
| # MCP Proxy Startup Script | ||
| # This script starts the MCP Proxy server with your configuration | ||
|
|
||
| cd /Users/jacques/DevFolder/mcp-proxy |
There was a problem hiding this comment.
The command cd /Users/jacques/DevFolder/mcp-proxy uses a hardcoded, absolute path that is specific to a user "Jacques". This makes the script non-portable and unusable for other users as-is.
If this script is intended for general use, it should be modified to work from any location where the repository is cloned, typically by:
- Assuming it's run from the repository root, or using relative paths from the script's location to find necessary files/directories (e.g.,
cd "$(dirname "$0")"to change to the script's directory first, then use relative paths). - Not changing the directory to a user-specific absolute path.
The examples/start-example.sh script is a good example of a more portable startup script. Could this script be made similarly portable, or was it perhaps a personal utility not intended for this PR?
README-SETUP.md
Outdated
|
|
||
| ## 🔒 Security Features | ||
|
|
||
| - **Tool Filtering**: Each server has explicit allow-lists of permitted tools | ||
| - **Authentication**: Uses auth tokens for proxy access | ||
| - **Safe Paths**: Filesystem access restricted to approved directories only | ||
| - **Environment Isolation**: Each MCP server runs in its own process | ||
|
|
||
| ## 🛠️ Management Commands | ||
|
|
||
| ### Start Proxy | ||
| ```bash | ||
| cd /Users/jacques/DevFolder/mcp-proxy | ||
| ./start-proxy.sh | ||
| ``` | ||
|
|
||
| ### Stop Proxy | ||
| Press `Ctrl+C` in the terminal running the proxy | ||
|
|
||
| ### Check Status | ||
| Visit: http://localhost:9090/health (if health endpoint exists) | ||
|
|
||
| ### View Logs | ||
| The proxy outputs detailed logs showing: | ||
| - Server connections | ||
| - Tool registrations | ||
| - Request routing | ||
| - Error debugging | ||
|
|
||
| ## 🔧 Customization | ||
|
|
||
| ### Adding New MCP Servers | ||
| Edit `proxy-config.json` and add to the `mcpServers` section: | ||
|
|
||
| ```json | ||
| "your-new-server": { | ||
| "command": "npx", | ||
| "args": ["-y", "your-mcp-package"], | ||
| "env": { | ||
| "API_KEY": "your-api-key" | ||
| }, | ||
| "options": { | ||
| "toolFilter": { | ||
| "mode": "allow", | ||
| "list": ["tool1", "tool2"] | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ### Removing Servers | ||
| Simply delete the server entry from `proxy-config.json` | ||
|
|
||
| ### Updating Tool Filters | ||
| Modify the `toolFilter.list` arrays to add/remove allowed tools | ||
|
|
||
| ## 🚨 Troubleshooting | ||
|
|
||
| ### Proxy Won't Start | ||
| - Check if port 9090 is available: `lsof -i :9090` | ||
| - Verify all MCP commands are installed (npx, uvx, etc.) | ||
| - Check file paths in configuration | ||
|
|
||
| ### Claude Can't Connect | ||
| - Ensure proxy is running: `./start-proxy.sh` | ||
| - Verify claude-config.json is in the right location | ||
| - Restart Claude Desktop after config changes | ||
|
|
||
| ### Individual Servers Failing | ||
| - Check the proxy logs for specific error messages | ||
| - Verify environment variables and API keys | ||
| - Test individual servers directly if needed | ||
|
|
||
| ### Missing Tools | ||
| - Check proxy logs for "Adding tool" messages | ||
| - Verify tool names in toolFilter lists match exactly | ||
| - Some servers may need additional setup or API keys | ||
|
|
||
| ## 🎉 Benefits | ||
|
|
||
| ✅ **Simplified Management**: One config file instead of 15+ | ||
| ✅ **Better Security**: Centralized tool filtering and access control | ||
| ✅ **Easier Debugging**: Single log output for all servers | ||
| ✅ **Performance**: Reduced Claude startup time | ||
| ✅ **Maintainability**: Easy to add/remove servers | ||
| ✅ **Reliability**: Failed servers don't break others | ||
|
|
||
| ## 📞 Support | ||
|
|
||
| If you need to modify this setup: | ||
| 1. Edit `proxy-config.json` for server changes | ||
| 2. Run `./start-proxy.sh` to restart | ||
| 3. Check logs for any issues | ||
| 4. Update tool filters as needed | ||
|
|
||
| --- | ||
|
|
||
| **Created**: May 25, 2025 | ||
| **Version**: 1.0 | ||
| **Proxy**: TBXark/mcp-proxy v1.0.0 |
There was a problem hiding this comment.
This entire file appears to be personalized for a specific user ("Jacques") and contains several pieces of user-specific information, which makes it unsuitable for general documentation aimed at all users. For example:
- The title itself: "Jacques' MCP Proxy Setup" (line 1).
- Hardcoded absolute paths like
/Users/jacques/DevFolder/mcp-proxy(e.g., lines 28, 43, 80). - A hardcoded auth token
mcp-proxy-token-2025(line 52). - The creation date is set in the future:
May 25, 2025(line 165).
If this PR aims to provide documentation for a general audience (as suggested by the PR description "help users get started"), could this file be generalized by removing all user-specific details and using placeholders? Alternatively, if this was a personal note, perhaps it wasn't intended to be part of this PR?
| cp "~/Library/Application Support/Claude/claude_desktop_config.json" \ | ||
| "~/Library/Application Support/Claude/claude_desktop_config.json.backup" | ||
|
|
||
| # Update with proxy config (edit paths first!) | ||
| cp claude-config.json "~/Library/Application Support/Claude/claude_desktop_config.json" |
There was a problem hiding this comment.
The Claude Desktop configuration path ~/Library/Application Support/Claude/claude_desktop_config.json is specific to macOS. While this might be the primary platform for many users, it could be helpful to clarify this for users on other operating systems.
Consider adding a note like "On macOS, the configuration file is typically located at..." or, if Claude Desktop supports other OSes with different config paths, mentioning those as well or stating that the provided path is macOS-specific.
examples/configs/simple-example.json
Outdated
| "args": [ | ||
| "-y", | ||
| "@modelcontextprotocol/server-filesystem", | ||
| "/Users/username/Documents" |
There was a problem hiding this comment.
The placeholder path /Users/username/Documents is somewhat specific to Unix-like systems and a common, but still specific, user directory structure.
To make it more universally understandable and less prescriptive, especially for users on different operating systems (e.g., Windows), could you consider using a more generic placeholder?
For example: /path/to/your/documents or /data/shared_files.
"/path/to/your/documents"
| "/Users/username/Desktop", | ||
| "/Users/username/Downloads", | ||
| "/Users/username/DevFolder" |
There was a problem hiding this comment.
Similar to other example files, the placeholder paths like /Users/username/Desktop are a bit specific to Unix-like systems.
To improve general applicability, would it be possible to use more generic placeholders here as well?
For example:
/path/to/your/desktop/path/to/your/downloads/path/to/your/dev_folder
"/path/to/your/desktop",
"/path/to/your/downloads",
"/path/to/your/dev_folder"
- Remove user-specific files (README-SETUP.md, start-proxy.sh) - Use generic path placeholders instead of OS-specific paths - Add multi-platform support for Claude Desktop config paths - Clarify Python package installation methods (uv vs pip) - Remove hardcoded paths to improve portability Fixes all critical, high, and medium severity issues identified in the automated code review.
🔧 Fixes Applied Based on Code ReviewThank you @gemini-code-assist for the thorough review! I've addressed all the identified issues: ✅ Critical Issues Fixed:
✅ High & Medium Issues Fixed:
✅ Additional Improvements:
📋 What's Now Included:
The contribution is now ready for general use and follows best practices for open source documentation. All examples use placeholder values and work across different operating systems. Thanks for helping improve the quality of this contribution! 🙏 |
|
Thank you, @jlwainwright, for the detailed update and for addressing the feedback from the previous review! It's great to see that the critical issues regarding hardcoded paths and personal information have been resolved. The changes you've made, particularly the use of generic path placeholders, multi-platform support, and removal of user-specific references, significantly improve the portability and security of the examples and documentation. The clarified Python installation steps and OS-specific instructions are also valuable additions. The contribution now looks much more robust and suitable for a wider audience. Excellent work incorporating the suggestions and enhancing the overall quality! 🙏 |
📋 Summary
This PR adds comprehensive configuration examples and documentation to help users get started with MCP Proxy more easily. The examples demonstrate various configuration patterns, security best practices, and integration scenarios.
🎯 What's Added
Configuration Examples
simple-example.json) - Minimal setup with 2 servers for beginnerscomprehensive-example.json) - Full-featured setup showcasing all optionsclaude-desktop-config.json) - Integration with Claude DesktopDocumentation
examples/README.md) - Comprehensive guide covering:Utilities
start-example.sh) - Easy launcher for testing different configurations🔍 Key Features Demonstrated
🔒 Security Focus
🎯 Use Cases
🧪 Testing
The startup script includes configuration validation and provides clear error messages for common issues.
# Test the examples ./examples/start-example.sh simple ./examples/start-example.sh comprehensive📚 Community Value
This addition significantly lowers the barrier to entry for new MCP Proxy users while providing advanced patterns for experienced users. The documentation answers common configuration questions and promotes security best practices.
Type: Enhancement
Breaking Changes: None
Documentation: Included