Add `list_sources` MCP tool to expose per-source connection status

[bkurinsky]

Summary

DBHub currently has no way to inspect which configured sources are reachable without actually executing a query against each one. When using ephemeral access tools like StrongDM or Teleport, source availability can change between sessions, and there is no mechanism for an AI client or user to know which sources are up before attempting to use them.

Problem

• No MCP tool exists to check source connectivity status
• With lazy = true, connection failures are silent until a query is attempted
• AI clients (e.g. Claude) have no way to inform the user which sources are available at the start of a session
• Diagnosing "why did my query fail" requires trial-and-error across sources
• Particularly painful in environments using ephemeral access managers (StrongDM, Teleport, etc.) where port availability changes dynamically

Proposed Solution

Add a new built-in MCP tool - list_sources - that returns the connection status of all configured sources:

• Reports each source id, type, and current connection state (connected, unavailable, lazy/pending)
• For unavailable sources, optionally surfaces the connection error message
• Does not require a query to be executed against the source
• For lazy sources that have not yet been accessed, attempts a lightweight connectivity check (e.g. TCP ping or equivalent) rather than a full connection

Usage Example

An AI client could call list_sources at the start of a session and receive:

[
  { "id": "production", "status": "connected" },
  { "id": "staging", "status": "unavailable", "error": "connection refused on port 12345" },
  { "id": "mysql_test", "status": "lazy/pending" }
]

This allows the client to immediately inform the user which sources are ready and which require attention (e.g. refreshing ephemeral access), rather than failing silently mid-session.

Implementation Notes

• New tool registered alongside execute_sql and search_objects
• For already-connected sources: return cached connection state
• For lazy sources: attempt a lightweight reachability check without full auth handshake if possible, or return lazy/pending if a check is not feasible
• No query execution or schema access required
• Should be read-only and safe to call at any time

Environment

• Affects: All transports (STDIO, HTTP)
• Particularly impactful for multi-source TOML configurations
• Pairs naturally with the existing lazy source option

Priority

Low/Medium - does not block core functionality but meaningfully improves observability and usability in production multi-source setups.

[tianzhou]

@bkurinsky pls describe your real use case and why this feature could help in particular

[bkurinsky]

@tianzhou - absolutely, thanks for the quick response

Our team uses DBHub as an MCP server with a TOML multi-source (5+ sources) config, where all sources route through StrongDM with some time-limited creds/access.

Should that access change or expire, the DBHub config will fail at startup - taking down all sources, not just those that are no longer available. We found lazy = true flag which solves the startup crash, but leaves us blind to which sources are actually reachable at any given moment.

Something like a list_sources or list_status tool would allow an AI client to proactively flag when a specific source is down rather than the user discovering it mid-workflow via a failed query.

[tianzhou]

@bkurinsky interesting case. Let me think about it.

BTW, have you considered other workaround?

FWIW, I just added config hot reload https://dbhub.ai/config/toml#hot-reload

[bkurinsky]

@tianzhou - nice, the hot reload does help by reconnecting those dropped sources, but in our case it only triggers on config file changes - not when an external provider (like StrongDM) revokes or restores access. lazy = true remains our main workaround, some type of status by source closes the final gap - not required just helpful!

[MarlzRana]

Hey folks,

I also want to see a list_sources tool, my issue is a bit different though, and mine is just to solve the context complexity issue one runs into as they add more sources.

I have a WIP PR here: #277

[MarlzRana]

The PR is now ready: #277

Let's consider adding extra meta fields to the list_sources tool in a follow up - the diff is already quite big! 😅

cc @tianzhou & @bkurinsky (not sure how GitHub notifications work, but hopefully this pings you both)