MCP IDE Bridge
by Mvp2o-ai
README.md
# MCP IDE Bridge
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](https://www.docker.com/)
[](https://spec.modelcontextprotocol.io/)
## 🎬 Demo Video
<div align="center">
<table>
<tr>
<td align="center" width="50%"><b>FRONT END WEB APP<br/>CURSOR IDE</b></td>
<td align="center" width="50%"><b>BACK END API<br/>CURSOR IDE</b></td>
</tr>
<tr>
<td colspan="2">
<a href="https://www.youtube.com/watch?v=TA97TGoOMJA" target="_blank">
<img
src="https://img.youtube.com/vi/TA97TGoOMJA/maxresdefault.jpg"
alt="MCP IDE Bridge Demo"
style="
border: 7px solid #e5534b;
border-radius: 14px;
padding: 0;
box-shadow: 0 0 36px 8px #e5534b, 0 0 0 4px #fff inset;
transition: box-shadow 0.3s;
"
>
</a>
</td>
</tr>
</table>
</div>
<p align="center"><i>
Click the image above to watch the live demo of MCP IDE Bridge in action!<br>
<b>This shows two Cursor IDEs (front end and back end) collaborating in real time via the IDE Bridge.</b>
</i></p>
A stateless, open source MCP (Model Context Protocol) HTTP Streamable server that enables **client-to-client communication** between IDEs and development tools. This opens up a new dimension of collaboration beyond traditional MCP client-server interactions.
**🚀 Perfect for**: Cross-IDE collaboration, team development workflows, AI agent coordination, and seamless tool integration.
## 🌟 What Makes This Special?
### Traditional MCP vs MCP IDE Bridge
| Traditional MCP | MCP IDE Bridge |
|----------------|----------------|
| Client ↔ Server | Client ↔ Server ↔ Client |
| One-way communication | Bidirectional messaging |
| Tool execution only | Real-time collaboration |
| Single IDE focus | Multi-IDE coordination |
### Real-World Use Cases
**🎯 IDE Collaboration**
- **Cursor ↔ Cursor**: Share code snippets, debugging sessions, or pair programming
- **Cursor ↔ VS Code**: Cross-editor communication and file sharing
- **Windsurf ↔ Any IDE**: AI agent coordination across different development environments
- **Team Workflows**: Coordinate multiple developers working on the same project
**🤖 AI Agent Coordination**
- Agent-to-agent communication for complex workflows
- Distributed AI processing across multiple tools
- Human-in-the-loop collaboration with AI assistants
## 🏗️ Architecture
### Client-to-Client Communication
```
IDE A (Cursor) ←→ MCP IDE Bridge ←→ IDE B (VS Code)
↑ ↑ ↑
MCP Client Message Relay MCP Client
```
### Key Components
- **Message Relay**: Stateless server that routes messages between clients
- **Client Registry**: Dynamic client discovery and registration
- **Message Queues**: Per-recipient queues with automatic expiration
- **HTTP Streamable**: Latest MCP transport for real-time communication
## 🚀 Quick Start
### 1. Start the Server
**Docker (Recommended):**
```bash
docker run -d --name mcp-ide-bridge -p 8111:8111 mcp-messaging-server
```
**Default Configuration:**
- **Port**: 8111 (both external and internal)
- **Host**: 0.0.0.0 (accepts connections from any interface)
- **Transport**: HTTP Streamable (MCP latest)
- **Health Check**: Built-in endpoint monitoring
**Python (Development Setup):**
```bash
# First-time setup (see Local Development section for full instructions)
pip install -r requirements.txt && pip install -e .
# Run server
python -m mcp_messaging.server --port 8111
```
### 2. Configure Your IDE
Create `mcp_recipients.json` in your project root. **Each project gets ONE file with its own unique ID and list of recipients it can communicate with:**
```json
{
"my_id": "myproject_cursor",
"recipients": {
"teammate_vscode": {
"name": "Teammate's Project",
"description": "My teammate's project in VS Code"
},
"aiagent_windsurf": {
"name": "AI Agent Project",
"description": "AI agent development in Windsurf"
}
},
"server_info": {
"url": "http://localhost:8111/mcp/",
"transport": "http_streamable"
}
}
```
**🤖 AI Agent Generation**: Your IDE's AI agent can generate this file! Simply ask:
- **Cursor**: "Generate an mcp_recipients.json for my project"
- **VS Code**: "Create mcp_recipients.json configuration for my team"
- **Windsurf**: "Help me set up mcp_recipients.json for collaboration"
**📁 Multi-Project Examples**: See `examples/multi-project-setup/` for examples showing how different projects communicate. **Each project file must be named `mcp_recipients.json`** - the filename examples in that folder are just for reference.
### 3. Connect Your IDE
**Cursor IDE:**
1. Create `.cursor/mcp.json`:
```json
{
"mcpServers": {
"messaging-server": {
"url": "http://localhost:8111/mcp/",
"type": "streamable-http",
"description": "MCP HTTP Streamable messaging server for client-to-client communication"
}
}
}
```
2. Open Command Palette (`Cmd/Ctrl + Shift + P`)
3. Search for "MCP: Connect to Server"
4. Enter: `http://localhost:8111/mcp/`
**VS Code:**
1. Install MCP extension from marketplace
2. Create `mcp_recipients.json` in project root
3. Configure MCP settings in VS Code preferences
4. Use MCP commands to connect and collaborate
**Windsurf:**
1. Create `mcp_recipients.json` in project root
2. Open Windsurf settings → MCP configuration
3. Add server URL: `http://localhost:8111/mcp/`
4. Start messaging with other IDEs
**Claude Desktop:**
1. Create `mcp_recipients.json` in project root
2. Open Claude Desktop settings → MCP configuration
3. Add server URL: `http://localhost:8111/mcp/`
4. Use Claude's MCP integration to communicate
**JetBrains IDEs (IntelliJ, PyCharm, etc.):**
1. Install MCP plugin from plugin marketplace
2. Create `mcp_recipients.json` in project root
3. Configure MCP server in plugin settings
4. Use MCP tools from the IDE
**Note**: Each IDE requires both `mcp_recipients.json` (for messaging) and IDE-specific MCP configuration (for connection). **Each project gets ONE `mcp_recipients.json` file with its own unique ID and recipient list.** The file must be named exactly `mcp_recipients.json` and placed in the **project root** for easy discovery by IDE agents. See `examples/multi-project-setup/README.md` for detailed setup instructions.
## 🔗 Non-IDE Clients (LangChain, mcp-use, Custom Apps)
### Overview
Non-IDE clients use the **exact same MCP protocol** as IDE clients. The only difference is how they provide their configuration:
- **IDE clients**: Read `mcp_recipients.json` from local file system
- **Non-IDE clients**: Provide `recipients_config` as parameter to MCP tools
**No registration, no REST endpoints, no special setup** - just parameter injection!
This enables seamless integration with frameworks like **LangChain**, **mcp-use**, **custom Python scripts**, and **web applications**.
### Architecture
```
Non-IDE Client (LangChain/mcp-use)
↓
Client wrapper adds recipients_config parameter
↓
Standard MCP Tools (same as IDE clients)
↓
MCP IDE Bridge ←→ IDE Clients
```
### Setup - Client Wrapper Approach
Create a wrapper that automatically injects your configuration:
**LangChain Integration:**
```python
from mcp import Client
class MCPClientWrapper:
def __init__(self, mcp_url, recipients_config):
self.client = Client(mcp_url)
self.recipients_config = recipients_config
self.my_id = recipients_config.get("my_id")
def get_my_identity(self):
# Inject recipients_config parameter
return self.client.call_tool("get_my_identity", {
"client_id": self.my_id,
"recipients_config": self.recipients_config
})
def send_message(self, recipient_ids, messages):
return self.client.call_tool("send_message_without_waiting", {
"sender_id": self.my_id,
"recipient_ids": recipient_ids if isinstance(recipient_ids, list) else [recipient_ids],
"messages": messages if isinstance(messages, list) else [messages]
})
def get_messages(self):
return self.client.call_tool("get_messages", {
"client_id": self.my_id
})
# Usage
recipients_config = {
"my_id": "my-langchain-app",
"recipients": {
"frontend_cursor": {
"name": "Frontend Team Cursor",
"description": "Frontend development in Cursor IDE"
},
"backend_vscode": {
"name": "Backend Team VS Code",
"description": "Backend API development in VS Code"
}
},
"server_info": {
"host": "localhost",
"port": 8111
}
}
# Initialize wrapper
mcp_client = MCPClientWrapper("http://localhost:8111/mcp/", recipients_config)
# Use exactly like IDE clients
identity = mcp_client.get_my_identity()
print(identity)
response = mcp_client.send_message(["frontend_cursor"], ["Please update the user authentication flow"])
messages = mcp_client.get_messages()
```
**mcp-use Integration:**
```python
import mcp_use
# Same wrapper pattern
wrapper = MCPClientWrapper("http://localhost:8111/mcp/", recipients_config)
wrapper.send_message(["team_cursor"], ["Task completed!"])
```
### Real-World Implementation: Proxy Pattern
For **production web applications**, the recommended approach is a **proxy/interceptor pattern** that selectively handles messaging tools:
**Next.js API Route Example (dyson_frontend implementation):**
```typescript
// app/api/mcp-proxy/route.ts
import { NextRequest } from 'next/server'
// Hardcoded configuration (no file dependencies)
const MCP_RECIPIENTS_CONFIG = {
my_id: 'dyson_frontend',
recipients: {
'miles_mcp_server': { name: 'Miles Primary MCP Server', description: 'Main backend API' },
'mcpresearchserver': { name: 'MCP Research Server', description: 'Research tools' },
'mcp-ide-bridge': { name: 'IDE Bridge', description: 'Cross-IDE communication' }
},
server_info: { host: 'localhost', port: 8111 }
}
// Only intercept these 4 messaging tools (99% of traffic passes through)
const INTERCEPTED_TOOLS = ['send_message_without_waiting', 'get_messages', 'get_my_identity', 'checkin_client']
export async function POST(request: NextRequest) {
const { tool_name, arguments: toolArgs, server_id } = await request.json()
// Only intercept messaging tools for ide-bridge
if (server_id === 'ide-bridge' && INTERCEPTED_TOOLS.includes(tool_name)) {
return handleMessagingTool(tool_name, toolArgs)
}
// Forward everything else unchanged
return forwardToMcp(server_id, tool_name, toolArgs)
}
async function handleMessagingTool(toolName: string, toolArgs: any) {
switch (toolName) {
case 'get_my_identity':
// Override with our config as markdown
return Response.json(formatConfigAsMarkdown(MCP_RECIPIENTS_CONFIG))
case 'send_message_without_waiting':
// Inject sender_id and validate recipients
return forwardToMcp('ide-bridge', toolName, {
...toolArgs,
sender_id: MCP_RECIPIENTS_CONFIG.my_id
})
case 'get_messages':
// Inject client_id
return forwardToMcp('ide-bridge', toolName, {
...toolArgs,
client_id: MCP_RECIPIENTS_CONFIG.my_id
})
case 'checkin_client':
// Inject client identity
return forwardToMcp('ide-bridge', toolName, {
client_id: MCP_RECIPIENTS_CONFIG.my_id,
name: 'Dyson Frontend App',
capabilities: 'Web application for AI agent coordination'
})
}
}
function formatConfigAsMarkdown(config: any): string {
const recipientRows = Object.entries(config.recipients).map(([id, info]: [string, any]) =>
`| ${id} | ${info.description} | No URL |`
).join('\n')
return `# 🆔 MCP Client Identity & Recipients
## Your Client ID: \`${config.my_id}\`
## Available Recipients
| Client ID | Description | URL |
|-----------|-------------|-----|
${recipientRows}
## Usage: Use your client ID in messaging tools...`
}
```
**Setup Steps for Non-IDE Clients:**
1. **Create MCP proxy endpoint** (`/api/mcp-proxy` or equivalent)
2. **Hardcode your recipient configuration** (no `mcp_recipients.json` files needed)
3. **Intercept only messaging tools:** `send_message_without_waiting`, `get_messages`, `get_my_identity`, `checkin_client`
4. **Inject required parameters** where missing (sender_id, client_id, etc.)
5. **Override `get_my_identity`** to return your config as markdown
6. **Forward everything else unchanged** (conservative approach)
**Framework Examples:**
```python
# Express.js
app.post('/mcp-proxy', (req, res) => {
const { tool_name, server_id } = req.body
if (server_id === 'ide-bridge' && MESSAGING_TOOLS.includes(tool_name)) {
return handleMessaging(tool_name, req.body.arguments)
}
return forwardToMcp(server_id, tool_name, req.body.arguments)
})
# Django
def mcp_proxy(request):
data = json.loads(request.body)
if data['server_id'] == 'ide-bridge' and data['tool_name'] in MESSAGING_TOOLS:
return handle_messaging(data['tool_name'], data['arguments'])
return forward_to_mcp(data['server_id'], data['tool_name'], data['arguments'])
# Flask
@app.route('/mcp-proxy', methods=['POST'])
def mcp_proxy():
data = request.json
if data['server_id'] == 'ide-bridge' and data['tool_name'] in MESSAGING_TOOLS:
return handle_messaging(data['tool_name'], data['arguments'])
return forward_to_mcp(data['server_id'], data['tool_name'], data['arguments'])
```
### Benefits
- **🔗 Simple Integration**: Same protocol as IDE clients
- **📡 No Special Setup**: Just parameter injection
- **🚀 Client-Side Control**: Proxy manages configuration
- **🛠️ Framework Agnostic**: Works with any MCP client library
- **🏗️ Conservative Approach**: Only intercepts what's needed (99% traffic unchanged)
- **💾 No File Dependencies**: Runtime configuration, no mcp_recipients.json required
- **🔧 Production Ready**: Real-world pattern used by active projects
## 📋 Available Tools
### Core Messaging Tools
| Tool | Description | Use Case |
|------|-------------|----------|
| `checkin_client` | Register your presence | Announce availability |
| `send_message_without_waiting` | Fire & forget messaging | **ONLY** messaging method |
| `get_messages` | **📬 ESSENTIAL** - Check for replies | **Required** after messaging |
| `get_my_identity` | Get configuration help | Setup assistance |
| `get_active_sessions` | View active connections | Monitor team activity |
### 🚀 Messaging Workflow
**MESSAGING PATTERN**: Fire-and-forget + get_messages for efficient communication:
**1. Send Messages (Fire & Forget):**
```bash
# Send to one or more recipients - INSTANT return, no blocking!
send_message_without_waiting(
sender_id="alice_cursor",
recipient_ids=["bob_vscode", "charlie_windsurf", "diana_jetbrains"],
messages=["Meeting in 5 minutes! Please confirm attendance."]
)
```
**2. Check for Replies:**
```bash
# Get replies from recipients
get_messages("alice_cursor")
# Returns responses from bob_vscode, charlie_windsurf, diana_jetbrains
```
**Message Patterns:**
```bash
# Different messages to different recipients
send_message_without_waiting(
sender_id="alice_cursor",
recipient_ids=["bob_vscode", "charlie_windsurf"],
messages=["Review auth module please", "Check UI components for responsiveness"]
)
# Single recipient
send_message_without_waiting(
sender_id="alice_cursor",
recipient_ids=["bob_vscode"],
messages=["Quick question about the API endpoint"]
)
# Then check for replies
get_messages("alice_cursor")
```
**Benefits:**
- ✅ **No Blocking**: Instant return, no waits
- ✅ **Scalable**: Works for one or more recipients efficiently
- ✅ **Fast**: No timeouts or blocking calls
- ✅ **Better UX**: Smooth, responsive messaging experience
### Example Workflows
**Team Collaboration**
```bash
# Developer A checks in
checkin_client("alice_cursor", "Alice", "Working on auth module")
# Developer A messages recipients
send_message_without_waiting("alice_cursor",
["bob_vscode", "charlie_windsurf", "diana_jetbrains"],
["Need code review on auth module - who's available?"])
# Developer A checks for replies
get_messages("alice_cursor")
# Returns: "I can help! - bob_vscode", "Busy until 3pm - charlie_windsurf"
```
**AI Agent Coordination**
```bash
# AI Agent 1 announces completion
send_message_without_waiting("ai_agent_1",
["ai_agent_2", "ai_agent_3", "human_reviewer"],
["Code review complete - ready for next phase"])
# Check for coordination responses
get_messages("ai_agent_1")
# Returns responses from recipients
```
## 🔒 Security Considerations
### Current State (Desktop Use)
**✅ Suitable for:**
- Local development teams
- Personal projects
- Desktop-only workflows
- Trusted network environments
**⚠️ Limitations:**
- No authentication beyond client IDs
- No encryption of messages
- No access control
- No audit logging
**🔐 Security Model:**
- Client IDs act as simple credentials
- Messages stored in memory only
- 5-minute automatic expiration
- No persistent storage
### Enterprise Solution
For production use, security, and team collaboration, we offer **MilesDyson.ai** - an enterprise-grade Agentic Platform as a Service (aPaaS) that addresses all security concerns:
- **🔐 Enterprise Authentication**: SSO, RBAC, and audit trails
- **🛡️ End-to-End Encryption**: All messages encrypted in transit and at rest
- **🌐 Global Infrastructure**: Multi-region deployment with 99.9% uptime
- **👥 Team Management**: User management, permissions, and collaboration tools
- **📊 Analytics**: Usage insights and performance monitoring
- **🔧 Enterprise Support**: Dedicated support and custom integrations
**[Learn More → MilesDyson.ai](https://milesdyson.ai)**
## 🧪 Testing
### MCP Test Harness (Recommended)
**NEW!** We've included a comprehensive MCP test harness (`test_mcp_client.py`) that makes testing all MCP tools easy and reliable:
```bash
# Test identity and configuration
python test_mcp_client.py get_my_identity
# Check in as a client
python test_mcp_client.py checkin_client --client_id "test-client" --name "Test Client" --capabilities "Testing tools"
# Send fire-and-forget messages
python test_mcp_client.py send_message_without_waiting \
--sender_id "test-client" \
--args '{"recipient_ids": ["target-client"], "messages": ["Hello from test harness!"]}'
# NEW! Broadcast messages (fire & forget)
# Same message to multiple recipients
python test_mcp_client.py send_message_without_waiting \
--sender_id "test-client" \
--args '{"recipient_ids": ["alice", "bob", "charlie"], "messages": ["Team meeting in 5 minutes!"]}'
# Different messages to different recipients
python test_mcp_client.py send_message_without_waiting \
--sender_id "test-client" \
--args '{"recipient_ids": ["alice", "bob"], "messages": ["Review the auth code", "Check the UI components"]}'
# Get pending messages
python test_mcp_client.py get_messages --client_id "test-client"
# Check server status
python test_mcp_client.py get_active_sessions
# Use custom JSON arguments
python test_mcp_client.py checkin_client --args '{"client_id": "custom", "name": "Custom Client"}'
```
**Features:**
- ✅ **Proper MCP Headers**: Handles `text/event-stream` and streaming responses correctly
- ✅ **Beautiful Output**: Clean markdown display with raw JSON debugging
- ✅ **All Tools Supported**: Test every MCP tool with proper argument handling
- ✅ **Flexible Arguments**: Use individual flags or JSON for complex parameters
- ✅ **Error Handling**: Clear error messages and troubleshooting info
**Installation:**
```bash
# Install required dependency
pip install requests
# Run any test
python test_mcp_client.py <tool_name> [arguments]
```
### Quick Connection Test
```bash
# Test server connectivity
curl -X GET http://localhost:8111/api/sessions
# Test MCP client connection
cd examples/client
python test_connection.py --mcp-localhost-port 8111
```
### Reference Client
The project includes a reference MCP client for testing:
```bash
cd examples/client
pip install -r requirements.txt
python client.py --mcp-localhost-port 8111
```
## 🏗️ Development
### Project Structure
```
src/mcp_messaging/
├── server.py # Main server implementation
├── models.py # Data models
└── queue_backends.py # Queue implementations
examples/
├── client/ # Reference MCP client
├── configs/ # Project-specific configurations
├── multi-project-setup/ # Multi-project IDE communication examples
│ ├── README.md # Comprehensive setup guide
│ ├── frontend-cursor.json
│ ├── backend-vscode.json
│ ├── rag-windsurf.json
│ ├── devops-jetbrains.json
│ └── ... # More project examples (filenames for reference only)
└── reference/ # Additional examples
test_mcp_client.py # MCP test harness for command-line testing
mcp_recipients.json # Example configuration (each project gets ONE file)
requirements.txt # Python dependencies
Dockerfile # Container support
```
**Note**: Each project gets ONE `mcp_recipients.json` file with its own unique ID and recipient list. The example filenames in `multi-project-setup/` are just for reference - your actual file must be named `mcp_recipients.json` in each project root.
### Local Development
```bash
# Clone and setup
git clone https://github.com/your-username/mcp-ide-bridge.git
cd mcp-ide-bridge
# Create and activate virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
# Install package in editable mode (REQUIRED for Python to find mcp_messaging module)
pip install -e .
# Run server
python -m mcp_messaging.server --port 8111
```
**⚠️ Important:** The `pip install -e .` step is **required** for Python to properly find the `mcp_messaging` module. Without this, you'll get `ModuleNotFoundError: No module named 'mcp_messaging'`.
## 🤝 Contributing
We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for:
- Development setup
- Code style guidelines
- Testing procedures
- Pull request process
## 📄 License
MIT License - see [LICENSE](LICENSE) for details.
## 🚀 Enterprise Solution
**Ready for production use?**
**[MilesDyson.ai](https://milesdyson.ai)** provides enterprise-grade MCP IDE Bridge with:
- 🔐 **Enterprise Security**: SSO, encryption, audit trails
- 🌐 **Global Infrastructure**: Multi-region, high availability
- 👥 **Team Management**: User management and collaboration tools
- 📊 **Analytics & Monitoring**: Usage insights and performance tracking
- 🔧 **Enterprise Support**: Dedicated support and custom integrations
**Perfect for:**
- Development teams
- Enterprise environments
- Production deployments
- Multi-organization collaboration
---
**Built with MCP HTTP Streamable transport** • **Powered by FastMCP** • **Made with ❤️ by MVP2o.ai**
## Contributing via Pull Requests
We welcome contributions! To submit changes:
1. Fork this repository and clone your fork.
2. Create a new feature branch from your fork's main branch:
```sh
git checkout -b feature/your-feature-name
```
3. Make your changes and commit them to your feature branch.
4. Push your branch to your fork:
```sh
git push --set-upstream origin feature/your-feature-name
```
5. Open a pull request from your fork/branch to the `main` branch of the upstream repository (Mvp2o-ai/mcp-ide-bridge).
6. Wait for review and feedback from the maintainers.
See `CONTRIBUTING.md` for more details.This server cannot be deployed
Maintenance
ActivityInactive
ResponsivenessNo issues