# Migration Guide: Experimental to Beta MCP Connectors

**KNOWN ISSUE: Space Configuration State**  
There is a known issue with the migration process that affects space-level connector enablement. See the "Known Issue" section below for critical details and workarounds.

## Overview  
This guide covers the migration process from the experimental MCP connector implementation to the new beta version. The beta version introduces significant architectural changes and improvements to the MCP connector functionality.

**Migration Summary:**

- Enable feature flags  
- Existing connectors preserved but disabled by default  
- Space configurations need to be refreshed  
- Clean state migration recommended

* * *

## Migration Process  
### Step 1: Enable MCP Admin Feature Flag  
1. Verify that the experimental flag `FEATURE_FLAG_ENABLE_MCP_UN_11963=true` is already enabled on `backend-service-chat`, `web-app-chat`, and `web-app-admin`.
2. Enable the MCP admin feature flag in the environment variables of `backend-service-chat`, `web-app-chat`, and `web-app-admin`:
   
   ```
   FEATURE_FLAG_ENABLE_MCP_ADMIN_UN_14099=true
   ```

3. Restart the application/services as required

### Step 2: Review Migrated Connectors in Admin Panel  
1. Navigate to the MCP Connector Admin Panel  
2. You will see all existing MCP connections listed as **disabled**  
3. Review each connector's configuration:
   
   - Connection details are preserved  
   - Tool configurations are maintained  
   - System prompts are retained

### Step 3: Understand Impact on Spaces  
**Immediate Effect:**
- All MCP connectors will **disappear from spaces** where they were previously configured  
- Users will no longer see these tools in their chat interface  
- **Space administrators will not see the connectors** in their `Sources & Tools` panel  
  
**This is expected behavior** while connectors remain disabled at the organization level.

### Step 4: Re-enable Connectors  
For each connector you want to restore:
1. Open the connector in the Admin Panel  
2. Review and update the configuration if needed  
3. Toggle the **Enable** slider to ON  
4. Save the changes

**Result:**
- The connector becomes visible in space configurations under `Sources & Tools > MCP Tools`  
- Space administrators can now enable it for their spaces

* * *

## Known Issue - Space Configuration State Issue  
**CRITICAL: Manual Space Configuration Required**  
There is a known issue affecting spaces that had a connector enabled before migration:

**The Problem:**
1. When you re-enable a connector from the Admin Panel  
2. It may appear as **enabled** **in space configurations where it was previously active**  
3. **However, the tools are NOT actually functional** in the space or chat interface  
4. The space appears correctly configured but the connector is not working

**The Workaround:**
Even if a connector shows as enabled in a space:
1. Space admin must open the space settings  
2. Make **any edit** (you can toggle a tool off and back on)  
3. Click **Update**

**Only after this manual save operation will the connector become truly functional in the space**.

**Why This Happens:** The migration preserves the enabled state in the space configuration database but does not properly initialize the connector's state in the spaces. The manual space update triggers the necessary initialization.

* * *

## Clean State Migration Approach (Recommended)  
Given the known issues and architectural changes, we **strongly recommend** starting from a clean state:

**For Connector Administrators:**
1. **Document existing configurations:**
   - Take screenshots of all connector settings
   - Export or copy system prompts
   - Note tool configurations  
2. **Delete all existing connectors** from the Admin Panel  
3. **Re-connect each MCP server** using the new beta interface:
   - Follow the standard connection process  
   - Reconfigure descriptions and system prompts  
   - Set up tools as needed  
   - Enable for organization

**For Space Administrators:**
1. Once connectors are re-enabled at the organization level  
2. In the space configuration, navigate to `Sources & Tools > MCP Tools`  
3. Enable desired connectors fresh (as if for the first time)  
4. Configure tool selections  
5. Save configuration

**Benefits of Clean State Migration:**
- Avoids known state synchronization issues  
- Ensures proper initialization of all components  
- Provides opportunity to review and optimize configurations  
- Eliminates potential hidden issues from migration

* * *

## Troubleshooting  
### Connector Still Showing as Disabled  
**Issue:** Re-enabled connector doesn't appear in space settings  
**Solution:**
1. Verify the connector is enabled in the Admin Panel  
2. Check that **Enable** slider is toggled ON  
3. Refresh the space configuration page  
4. If issue persists, try disabling and re-enabling the connector

### Tools Not Showing in Chat Despite Being Enabled  
**Issue:** Connector shows as enabled but tools don't work  
**Solution:** This is the known space configuration issue. Follow the workaround:
1. Open space settings  
2. Make any minor edit  
3. Click **Update**

### Unexpected Behavior After Migration  
**Issue:** Errors, missing data, or inconsistent states  
**Solution:**
1. Follow the clean state migration approach  
2. Delete affected connectors  
3. Reconnect and reconfigure from scratch  
4. Contact your Customer Success representative if issues persist

* * *

## Rollback Procedure  
If you need to rollback to the experimental version:
1. Disable MCP Admin feature flag in `backend-service-chat`, `web-app-chat`, and `web-app-admin`:
   
   ```
   FEATURE_FLAG_ENABLE_MCP_ADMIN_UN_14099=false
   ```

2. Restart application/services

* * *

## Additional Resources
- MCP Conectors for Admins
- [Managing MCP Tools in Spaces](https://docs.unique.ai/administrators/space-management/tools/mcp-tools)