[Bug]: SSE Tool Invocation Fails After Integration Type Migration post PR #678

[crivetimihai]

Incorrect Architecture Change - MCP Tools Wrongly Migrated to REST Type

Issue Summary

PR #678 incorrectly migrated MCP Gateway tools from integration_type: "MCP" to integration_type: "REST", fundamentally breaking the intended architecture and causing SSE-based MCP tools to fail with "400 Bad Request" errors.

Environment

• Branch: main
• Commit: 9ecd07d (post PR 452Remove-Integration-Type #678)
• Affected Components: Tool Service, Gateway Service, Admin UI, Database Schema, Tool Registration

Problem Description - Architectural Misunderstanding

PR #678 was intended to remove the ability to manually add MCP servers directly under the Tools UI, but instead incorrectly removed the "MCP" integration type entirely and migrated existing MCP tools to "REST" type. This violates the intended architecture:

Intended Architecture:

1. MCP Servers → Added only via Gateways → Auto-discover tools → Tools marked as integration_type: "MCP"
2. REST APIs → Added directly via Tools UI → Individual endpoints → Tools marked as integration_type: "REST"

What Should Have Been Done:

• Remove MCP server creation option from Tools UI
• Keep integration_type: "MCP" for gateway-discovered tools
• Keep integration_type: "REST" for manually added REST endpoints
• Update UI to prevent direct MCP server addition under Tools

What Was Actually Done (Incorrect):

• Removed "MCP" integration type entirely from schemas
• Migrated all existing MCP tools to integration_type: "REST"
• Left tool service logic expecting integration_type: "MCP"
• Broke the architectural separation between gateway-managed and directly-added tools

Reproduction Steps

1. Register an MCP gateway with SSE transport
2. Wait for tool discovery
3. Attempt to invoke any SSE-based tool via /rpc endpoint
4. Observe 400 Bad Request error

Expected Behavior

• Gateway-discovered MCP tools should have integration_type: "MCP"
• MCP tools should be invoked via the MCP SSE/HTTP client and return proper tool results
• Tools UI should only allow adding individual REST endpoints (integration_type: "REST")
• MCP servers should only be addable via Gateways interface

Actual Behavior

Tool invocation failed: Client error '400 Bad Request' for url 'https://example.com/sse'

• All tools (including MCP gateway tools) have integration_type: "REST"
• MCP tools are incorrectly routed through REST HTTP client instead of MCP client
• UI architectural separation between gateway-managed and direct tools is broken

Root Cause Analysis

PR #678 misunderstood the requirement. The issue was:

Original Problem (Correct):

• Users could manually add MCP servers directly in Tools UI, bypassing gateway management
• This created confusion between gateway-managed vs directly-added tools

Intended Solution (Correct):

• Remove MCP server creation option from Tools UI
• Keep integration_type: "MCP" for gateway-discovered tools
• Keep integration_type: "REST" for manually-added individual REST APIs

Actual Implementation (Incorrect):

• Removed "MCP" integration type entirely from schemas (mcpgateway/schemas.py)
• Migrated all existing MCP tools to integration_type: "REST"
• Left tool service logic correctly expecting integration_type: "MCP"
• Broke architectural distinction between tool sources

Current Workaround Applied

A temporary fix was applied to detect SSE tools within REST integration type:

if tool.integration_type == "REST":
    if tool.request_type and tool.request_type.upper() == "SSE":
        # Route to MCP SSE client logic (workaround)

This is a band-aid solution and should be reverted in favor of proper architecture.

Proper Fix Needed

The architectural fix requires reverting the incorrect changes and implementing the original intent:

1. Database Schema Restoration

• Restore integration_type: "MCP" as valid enum value in schemas
• Create migration to revert existing gateway tools back to integration_type: "MCP"
• Identify gateway-originated tools vs manually-added tools for proper classification

2. UI Changes Required

• Remove MCP server creation options from Tools UI (mcpgateway/templates/admin.html)
• Update Tools interface to only allow REST endpoint addition
• Ensure Gateway interface remains the only way to add MCP servers
• Update admin JavaScript to reflect this separation (mcpgateway/static/admin.js)

3. Service Logic Updates

• Revert the workaround in tool_service.py
• Ensure gateway service marks discovered tools as integration_type: "MCP"
• Maintain proper separation between MCP and REST tool handling

4. Validation Updates

• Update schemas to prevent manual MCP tool creation via Tools API
• Ensure gateway-discovered tools are properly typed as MCP
• Add validation to prevent integration type manipulation

Current Workaround Status

• ✅ SSE tools now properly invoke via MCP client (temporary fix)
• ✅ 400 Bad Request errors resolved (temporary fix)
• ⚠️ Architecture remains broken - tools should be type MCP, not REST
• ⚠️ UI still allows incorrect tool creation patterns

Impact

• Severity: Critical (architectural integrity compromised)
• Technical Debt: High (workaround masks underlying design violation)
• Scope: All MCP gateways, Tools UI, database consistency
• Users Affected: All deployments using MCP gateways
• Long-term Risk: Confusion between tool types, potential future breakages

Files Requiring Changes

• mcpgateway/schemas.py - Restore MCP integration type
• mcpgateway/templates/admin.html - Remove MCP creation from Tools UI
• mcpgateway/static/admin.js - Update UI logic
• mcpgateway/services/gateway_service.py - Ensure MCP tool typing
• mcpgateway/services/tool_service.py - Revert workaround after proper fix
• Database migration script - Revert tool type migration

Related Issues

• PR 452Remove-Integration-Type #678: "Remove Integration Type: MCP" (incorrectly implemented)
• Original requirement: Prevent manual MCP server addition in Tools UI
• Issue [Bug]: Unable to add multiple headers when adding a gateway through UI (draft) #526: Multi-header authentication (unrelated architectural change)

Remediation Priority

High Priority - This represents a fundamental architectural violation that should be corrected to maintain system integrity and prevent future confusion about tool types and their proper management interfaces.