fix: ensure consistent DbTool creation across gateway registration, updation and rediscovery after health check failure

[kanapuli]

🐛 Bug-fix PR

📌 Summary

Fixes inconsistent DbTool creation across gateway federation scenarios. When MCP gateways reconnected after health check failures or were updated, tools would lose critical federation metadata including federation_source, visibility, team_id, and owner_email, breaking team access controls and audit trails.

Due to this missing data, the newly discovered tools or the tools that have changed for an MCP server do not reflect in the UI and is unavailable for the gateway clients.

🔁 Reproduction Steps

1. Register a gateway with tools via /gateways endpoint
2. Wait for health check to fail. Modify the MCP server to support more tools
3. When gateway reconnects, observe that the new tools for the mcp server lose federation metadata and the visibility becomes private
4. Tools created during reconnection missing federation_source, team_id, visibility, etc.

🐞 Root Cause

• The toggle_gateway_status(), update_gateway(), and fetch_tools_after_oauth() methods created DbTool objects directly with incomplete metadata, while the original register_gateway() method created tools with complete federation context. - - This inconsistency caused tools to lose critical metadata during reconnection/update scenarios.

💡 Fix Description

• Added _create_db_tool() helper method that centralizes DbTool creation logic with consistent federation metadata
• Updated affected methods to use the helper instead of creating DbTool objects directly:
  • toggle_gateway_status() uses created_via="rediscovery"
  • update_gateway() uses created_via="update"
  • fetch_tools_after_oauth() uses created_via="oauth"
• Helper ensures all tools maintain complete federation metadata, audit trail, and naming consistency

🧪 Verification

Check	Command	Status
Lint suite	make lint	⏳
Unit tests	make test	✅
Coverage ≥ 90 %	make coverage	⏳
Manual regression no longer fails	Gateway service tests pass	✅

📐 MCP Compliance (if relevant)

• Matches current MCP spec
• No breaking change to MCP clients

✅ Checklist

• Code formatted (make black isort pre-commit)
• No secrets/credentials committed

Files Modified:

• mcpgateway/services/gateway_service.py - Added helper method and updated affected methods

Future Todos

• The same problem exist for mcp resources and prompts. If this PR gets merged, I can take a same approach to fix the other resources.

Before the Change

• A sample database record for the tools table where new mcp tools from the same MCP server lack metadata during rediscovery

After the Change

• The same MCP server tools after rediscovery after health check failures

[MohanLaksh]

@madhav165

PR Test Summary:

make serve - PASS
plus
make test - PASS (=== 2668 passed, 24 skipped, 814 warnings in 329.06s (0:05:29) ===)
make autoflake isort black flake8 - PASS - no errors
make pylint - 10/10 (Your code has been rated at 10.00/10 )
make smoketest - PASS - ✅ Smoketest passed!
make doctest - PASS - (750 passed, 7 skipped, 95 warnings in 25.60s)