@neomint-pst/mintapp-mcp-bridge

MINTapp MCP Bridge - Connects Claude Desktop directly to your MINTapp's HTTP MCP gateway via stdio

This package is specifically designed for MINTapp users who want to use their gateway's connected MCP servers directly in Claude Desktop. It acts as a bridge between Claude Desktop's stdio interface and MINTapp's HTTP MCP gateway.

✨ Features

• ✅ Purpose-Built for MINTapp - Specifically designed for MINTapp's HTTP MCP gateway
• ✅ Claude Desktop Integration - Uses Claude Desktop's native stdio transport
• ✅ No Setup Required - Distributed as standalone npm package
• ✅ Auto-Discovery - Automatically connects to MINTapp's default gateway port (3001)
• ✅ All Your Tools - Access tools from all your MINTapp-connected servers in Claude
• ✅ Error Handling - Comprehensive error handling with helpful messages

🚀 Quick Start

Prerequisites

• Node.js 16+ installed
• MINTapp running with connected MCP servers

Usage with Claude Desktop

1. Start MINTapp and connect to any MCP servers (the HTTP gateway starts automatically on port 3001)

2. Configure Claude Desktop by adding this to your claude_desktop_config.json:

{
  "mcpServers": {
    "mintapp-gateway": {
      "command": "npx",
      "args": ["-y", "@neomint-pst/mintapp-mcp-bridge"]
    }
  }
}

3. Restart Claude Desktop - All your MINTapp gateway tools are now available!

📁 Config File Locations

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\\Claude\\claude_desktop_config.json
• Linux: ~/.config/claude/claude_desktop_config.json

🔧 Configuration Options

Basic Usage (Default Port 3001)

{
  "mcpServers": {
    "mintapp-gateway": {
      "command": "npx",
      "args": ["-y", "@neomint-pst/mintapp-mcp-bridge"]
    }
  }
}

Custom Port

{
  "mcpServers": {
    "mintapp-gateway": {
      "command": "npx",
      "args": ["-y", "@neomint-pst/mintapp-mcp-bridge", "--port", "3002"]
    }
  }
}

With Debug Logging

{
  "mcpServers": {
    "mintapp-gateway": {
      "command": "npx",
      "args": ["-y", "@neomint-pst/mintapp-mcp-bridge", "--debug"]
    }
  }
}

🔧 Command Line Options

npx @neomint-pst/mintapp-mcp-bridge [options]

Options:
  --host <host>      Host to connect to (default: localhost)
  --port <port>      Port to connect to (default: 3001)
  --timeout <ms>     Connection timeout in ms (default: 30000)
  --debug            Enable debug logging
  --help, -h         Show help message

📋 How It Works

1. MINTapp starts and you connect to various MCP servers (filesystem, web-search, etc.)
2. HTTP Gateway auto-starts at http://localhost:3001 exposing all connected tools
3. Claude Desktop launches this bridge package via npx
4. Bridge connects to MINTapp's HTTP gateway and translates between HTTP and stdio
5. Claude sees all tools from your MINTapp gateway as if they were local MCP servers

Claude Desktop ←→ stdio ←→ MINTapp Bridge ←→ HTTP ←→ MINTapp Gateway ←→ Your MCP Servers

🛠 Typical Workflow

1. Start MINTapp

# Your MINTapp starts up
npm start

2. Connect MCP Servers in MINTapp

• Add filesystem server: /path/to/your/files
• Add web search server: @modelcontextprotocol/server-web-search
• Add any other MCP servers you need

3. Claude Desktop Configuration

{
  "mcpServers": {
    "mintapp": {
      "command": "npx",
      "args": ["-y", "@neomint-pst/mintapp-mcp-bridge"]
    }
  }
}

4. Use in Claude Desktop

All your MINTapp tools are now available in Claude Desktop! You can:

• Search the web
• Read and write files
• Use any other tools from your connected servers

🔍 Troubleshooting

"Connection refused" Error

Problem: Bridge can't connect to MINTapp's HTTP gateway

Solutions:

1. Make sure MINTapp is running and has at least one MCP server connected
2. Check that the HTTP gateway started on port 3001 (check MINTapp logs)
3. Try with debug logging: --debug flag
4. Verify port with custom port: --port <your-port>

"No tools available" in Claude Desktop

Problem: Bridge connects but Claude sees no tools

Solutions:

1. Ensure you have MCP servers connected in MINTapp
2. Check MINTapp's gateway status - should show running servers and tools
3. Try refreshing tools in MINTapp UI
4. Check debug logs for JSON-RPC communication issues

Connection Timeout

Solutions:

1. Increase timeout: --timeout 60000
2. Check MINTapp is responding (open http://localhost:3001 in browser)
3. Restart MINTapp to refresh the gateway

Debug Logging

Enable detailed logging to see what's happening:

{
  "mcpServers": {
    "mintapp": {
      "command": "npx",
      "args": ["-y", "@neomint-pst/mintapp-mcp-bridge", "--debug"]
    }
  }
}

🔐 Security

• Bridge only connects to localhost by default
• All communication happens locally between your processes
• No external network access required
• Security depends on your MINTapp configuration

📄 License

MIT License - see LICENSE file for details

🤝 Support

• GitHub Issues: https://github.com/neomint/mintapp-mcp-bridge/issues
• Email: [email protected]
• MINTapp Documentation: [Link to MINTapp docs when available]

🏷 Changelog

v1.0.0

• Initial release for MINTapp integration
• stdio to HTTP bridge functionality
• Claude Desktop compatibility
• Debug logging support
• Error handling and timeout configuration