# MCP IDE Bridge
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](https://www.docker.com/)
[](https://spec.modelcontextprotocol.io/)
## ๐ฌ Demo Video
FRONT END WEB APP
CURSOR IDE |
BACK END API
CURSOR IDE |
|
Click the image above to watch the live demo of MCP IDE Bridge in action!
This shows two Cursor IDEs (front end and back end) collaborating in real time via the IDE Bridge.
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 [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.