MCP Catalog

The MCP Catalog is the SQLite database mcp_catalog.db in the ProxySQL data directory. The v4.0.10 server constructs the live path as <datadir>/mcp_catalog.db; there is no MCP runtime variable that changes it.

For a typical Linux installation this is:

/var/lib/proxysql/mcp_catalog.db

The Query handler initializes and migrates the embedded catalog schema when the handler starts. The catalog stores backend discovery snapshots, LLM annotations, agent activity, search logs, and MCP query-tool statistics.

Released Table Inventory

Discovery and structure

schema_docs: Catalog documentation records.
runs: Discovery runs, target/protocol, start/finish state, and source/server metadata.
schemas: Schemas discovered in a run.
objects: Tables, views, routines, and triggers discovered in a run.
columns: Column metadata and derived flags.
indexes and index_columns: Index definitions and ordered index columns.
foreign_keys and foreign_key_columns: Foreign-key definitions and their column mappings.
view_dependencies: Dependencies from views to referenced objects.
inferred_relationships: Deterministic inferred relationships.
profiles: Sample/profile summaries for discovered objects or columns.

Agent and LLM context

agent_runs and agent_events: Agent session state and structured events.
llm_object_summaries: Natural-language object summaries.
llm_relationships: LLM-inferred relationships and confidence.
llm_domains and llm_domain_members: Logical domains and their object membership.
llm_metrics: LLM-authored metric definitions.
llm_question_templates: Reusable questions associated with catalog context.
llm_notes: Free-form LLM notes.

Search, rules, and usage

llm_search_log and rag_search_log: Search history.
query_tool_calls: Query-tool invocation log.
mcp_query_rules: Catalog-local rule representation used by the Query handler. The editable and runtime Admin tables are documented under MCP Tables.
stats_mcp_query_digest and stats_mcp_query_digest_reset: Catalog-side MCP digest accumulators projected into the SQL stats schema.
mcp_query_digest_persist: Internal persisted digest state.

The schema also creates FTS5 search structures used by catalog.search; those virtual/shadow tables are implementation details rather than operator-managed catalog tables.

Released Catalog Tools

All five tools are served by the functional /mcp/query handler, not by /mcp/stats or /mcp/rag.

Tool	Required arguments	Optional arguments	Behavior
`catalog.init`	None	`sqlite_path`	Reports the catalog as initialized. The live handler has already initialized its fixed `<datadir>/mcp_catalog.db`; this call does not switch the active database to another path.
`catalog.search`	`target_id`, `run_id`, `query`	`limit` (default 25), `object_type`, `schema_name`	FTS5 search over objects in one target/run.
`catalog.get_object`	`target_id`, `run_id`, plus `object_id` or `object_key`	`include_definition`, `include_profiles`	Returns an object with columns, indexes, foreign keys, and optional definition/profile data.
`catalog.list_objects`	`target_id`, `run_id`	`schema_name`, `object_type`, `order_by`, `page_size` (default 50), `page_token`	Paged object inventory for a discovery run.
`catalog.get_relationships`	`target_id`, `run_id`, plus `object_id` or `object_key`	`include_inferred`, `min_confidence`	Returns foreign keys, view dependencies, and optionally deterministic/LLM-inferred relationships.

Use list_targets first to obtain a target ID from the active MCP target profiles, then run discovery.run_static to populate a discovery run before searching it. See Query Tools and MCP Autodiscovery for the wider workflow.

Access and Safety

The catalog is managed through MCP tools; direct file edits while ProxySQL is using it are unsafe. Several Query tools write catalog state, including discovery, agent-event, and LLM upsert/add operations. Restrict the /mcp/query bearer token, the backend profile credentials, and filesystem access to the ProxySQL data directory.