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