Add GET /queries stored-query catalog endpoint

List a graph's mcp.expose stored queries as a typed tool catalog so a client
(the MCP server) can register them as tools without fetching .gq source.
Each entry carries name, MCP tool_name, description/instruction, a
read/mutate flag, and decomposed typed params (kind enum: string|bool|int|
bigint|float|date|datetime|blob|vector|list, plus item_kind for lists and
vector_dim) — so the consumer builds an input schema with a closed match and
never re-parses omnigraph type spelling. I64/U64 are bigint (string on the
wire): a JSON number loses precision past 2^53 and the engine already accepts
decimal strings.

Read-gated (works in default-deny; the catalog is graph-wide, authorized
against main). NOT Cedar-filtered per query yet — a reader can list a query
whose invoke_query they lack (documented gap until per-query authz lands);
invocation stays invoke_query-gated + deny==404.

- api: QueriesCatalogOutput / QueryCatalogEntry / ParamDescriptor / ParamKind
  + query_catalog_entry (reuses PropType::from_param_type_name; scalar_kind is
  exhaustive, so a new ScalarType is a compile error here until catalogued).
- GET /queries route in per_graph_protected (→ /graphs/{id}/queries in multi
  mode); OpenAPI regenerated; path allowlists updated.
- Tests: projection unit (every kind, list, vector, nullable, mutation,
  empty) + handler (exposed-only filter, read-gate probe-oracle, empty
  registry).

crates/omnigraph-server/src/api.rs

@@ -1,8 +1,11 @@
 use omnigraph::db::{GraphCommit, MergeOutcome, ReadTarget, SchemaApplyResult, Snapshot};
 use omnigraph::error::{MergeConflict, MergeConflictKind};
 use omnigraph::loader::{IngestResult, LoadMode};
+use crate::queries::StoredQuery;
 use omnigraph_compiler::SchemaMigrationStep;
+use omnigraph_compiler::query::ast::Param;
 use omnigraph_compiler::result::QueryResult;
+use omnigraph_compiler::types::{PropType, ScalarType};
 use serde::{Deserialize, Serialize};
 use serde_json::Value;
 use utoipa::{IntoParams, ToSchema};
@@ -330,6 +333,132 @@ pub enum InvokeStoredQueryResponse {
     Change(ChangeOutput),
 }
 
+/// The kind of a stored-query parameter, decomposed so a client (e.g. an
+/// MCP server) can build a typed input schema with a closed `match` and
+/// never re-parse omnigraph's type spelling. `bigint`/`date`/`datetime`/
+/// `blob` are carried as JSON strings on the wire: a 64-bit integer past
+/// 2^53 loses precision as a JSON number, and Date/DateTime are ISO
+/// strings, Blob a blob-URI string.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, ToSchema)]
+#[serde(rename_all = "snake_case")]
+pub enum ParamKind {
+    String,
+    Bool,
+    Int,
+    #[serde(rename = "bigint")]
+    BigInt,
+    Float,
+    Date,
+    #[serde(rename = "datetime")]
+    DateTime,
+    Blob,
+    Vector,
+    List,
+}
+
+/// One declared parameter of a stored query, projected for the catalog.
+#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
+pub struct ParamDescriptor {
+    pub name: String,
+    pub kind: ParamKind,
+    /// Element kind when `kind == list` (always a scalar — the grammar
+    /// forbids lists of vectors or nested lists).
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub item_kind: Option<ParamKind>,
+    /// Dimension when `kind == vector`.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub vector_dim: Option<u32>,
+    /// `false` → the caller must supply it; `true` → optional.
+    pub nullable: bool,
+}
+
+/// One entry in the stored-query catalog (`GET /queries`).
+#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
+pub struct QueryCatalogEntry {
+    /// Registry key / invoke path segment (`POST /queries/{name}`).
+    pub name: String,
+    /// MCP tool id (the `tool_name` override, else `name`).
+    pub tool_name: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub description: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub instruction: Option<String>,
+    /// `true` for a stored mutation → an MCP read-only hint of `false`.
+    pub mutation: bool,
+    pub params: Vec<ParamDescriptor>,
+}
+
+/// Response for `GET /queries`: the `mcp.expose` subset of a graph's
+/// stored-query registry, each with typed parameters.
+#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
+pub struct QueriesCatalogOutput {
+    pub queries: Vec<QueryCatalogEntry>,
+}
+
+/// Total map from a resolved scalar to its catalog kind. Exhaustive on
+/// purpose: a new `ScalarType` is a compile error here until catalogued.
+fn scalar_kind(scalar: ScalarType) -> ParamKind {
+    match scalar {
+        ScalarType::String => ParamKind::String,
+        ScalarType::Bool => ParamKind::Bool,
+        ScalarType::I32 | ScalarType::U32 => ParamKind::Int,
+        ScalarType::I64 | ScalarType::U64 => ParamKind::BigInt,
+        ScalarType::F32 | ScalarType::F64 => ParamKind::Float,
+        ScalarType::Date => ParamKind::Date,
+        ScalarType::DateTime => ParamKind::DateTime,
+        ScalarType::Blob => ParamKind::Blob,
+        ScalarType::Vector(_) => ParamKind::Vector,
+    }
+}
+
+fn param_descriptor(param: &Param) -> ParamDescriptor {
+    match PropType::from_param_type_name(&param.type_name, param.nullable) {
+        Some(pt) if pt.list => ParamDescriptor {
+            name: param.name.clone(),
+            kind: ParamKind::List,
+            item_kind: Some(scalar_kind(pt.scalar)),
+            vector_dim: None,
+            nullable: param.nullable,
+        },
+        Some(pt) => {
+            let (kind, vector_dim) = match pt.scalar {
+                ScalarType::Vector(dim) => (ParamKind::Vector, Some(dim)),
+                other => (scalar_kind(other), None),
+            };
+            ParamDescriptor {
+                name: param.name.clone(),
+                kind,
+                item_kind: None,
+                vector_dim,
+                nullable: param.nullable,
+            }
+        }
+        // Unreachable for a parsed query (every declared param type is
+        // grammatical); fall back to an opaque string so the field is still
+        // usable rather than dropped.
+        None => ParamDescriptor {
+            name: param.name.clone(),
+            kind: ParamKind::String,
+            item_kind: None,
+            vector_dim: None,
+            nullable: param.nullable,
+        },
+    }
+}
+
+/// Project a loaded stored query into its catalog entry (typed params,
+/// MCP tool name, read/mutate flag, description/instruction).
+pub fn query_catalog_entry(query: &StoredQuery) -> QueryCatalogEntry {
+    QueryCatalogEntry {
+        name: query.name.clone(),
+        tool_name: query.effective_tool_name().to_string(),
+        description: query.decl.description.clone(),
+        instruction: query.decl.instruction.clone(),
+        mutation: query.is_mutation(),
+        params: query.decl.params.iter().map(param_descriptor).collect(),
+    }
+}
+
 #[derive(Debug, Clone, Default, Serialize, Deserialize, ToSchema)]
 pub struct SchemaApplyRequest {
     /// Project schema in `.pg` source form. The diff against the current

crates/omnigraph-server/src/lib.rs

@@ -26,7 +26,7 @@ use api::{
     BranchMergeOutput, BranchMergeRequest, ChangeOutput, ChangeRequest, CommitListOutput,
     CommitListQuery, ErrorCode, ErrorOutput, ExportRequest, GraphInfo, GraphListResponse,
     HealthOutput, IngestOutput, IngestRequest, InvokeStoredQueryRequest,
-    InvokeStoredQueryResponse, QueryRequest, ReadOutput, ReadRequest,
+    InvokeStoredQueryResponse, QueriesCatalogOutput, QueryRequest, ReadOutput, ReadRequest,
     SchemaApplyOutput, SchemaApplyRequest, SchemaOutput, SnapshotQuery, ingest_output,
     schema_apply_output, snapshot_payload,
 };
@@ -98,6 +98,7 @@ fn hash_bearer_token(token: &str) -> BearerTokenHash {
         server_export,
         #[allow(deprecated)] server_change,
         server_mutate,
+        server_list_queries,
         server_invoke_query,
         server_schema_apply,
         server_schema_get,
@@ -1092,6 +1093,7 @@ pub fn build_app(state: AppState) -> Router {
             server_change
         }))
         .route("/mutate", post(server_mutate))
+        .route("/queries", get(server_list_queries))
         .route("/queries/{name}", post(server_invoke_query))
         .route("/schema", get(server_schema_get))
         .route("/schema/apply", post(server_schema_apply))
@@ -2274,6 +2276,51 @@ async fn server_invoke_query(
     }
 }
 
+#[utoipa::path(
+    get,
+    path = "/queries",
+    tag = "queries",
+    operation_id = "list_queries",
+    responses(
+        (status = 200, description = "Stored-query catalog (the mcp.expose subset, with typed params)", body = QueriesCatalogOutput),
+        (status = 401, description = "Unauthorized", body = ErrorOutput),
+        (status = 403, description = "Forbidden", body = ErrorOutput),
+    ),
+    security(("bearer_token" = [])),
+)]
+/// List the graph's exposed stored queries as a typed tool catalog.
+///
+/// Returns the `mcp.expose == true` subset of the `queries:` registry, each
+/// with its MCP tool name, read/mutate flag, description/instruction, and
+/// typed parameters — enough for a client to register them as tools without
+/// fetching `.gq` source. Read-gated; the catalog is graph-wide (branch
+/// independent — `read` is authorized against `main`). **Not** Cedar-filtered
+/// per query yet, so it can list a query whose `invoke_query` the caller
+/// lacks (a known gap until per-query authorization lands).
+async fn server_list_queries(
+    Extension(handle): Extension<Arc<GraphHandle>>,
+    actor: Option<Extension<ResolvedActor>>,
+) -> std::result::Result<Json<QueriesCatalogOutput>, ApiError> {
+    authorize_request(
+        actor.as_ref().map(|Extension(actor)| actor),
+        handle.policy.as_deref(),
+        PolicyRequest {
+            action: PolicyAction::Read,
+            branch: Some("main".to_string()),
+            target_branch: None,
+        },
+    )?;
+    let queries = match handle.queries.as_ref() {
+        Some(registry) => registry
+            .iter()
+            .filter(|q| q.expose)
+            .map(api::query_catalog_entry)
+            .collect(),
+        None => Vec::new(),
+    };
+    Ok(Json(QueriesCatalogOutput { queries }))
+}
+
 #[utoipa::path(
     get,
     path = "/schema",

crates/omnigraph-server/src/queries.rs

@@ -563,4 +563,64 @@ embedding: Vector(4)
         let report = check(&reg, &test_catalog());
         assert!(report.is_clean(), "no breakage or warning expected: {:?}", report);
     }
+
+    // --- catalog projection (api::query_catalog_entry) ---
+
+    #[test]
+    fn catalog_entry_projects_every_param_kind() {
+        use crate::api::{self, ParamKind};
+        let reg = QueryRegistry::from_specs(vec![spec_tool(
+            "all_types",
+            "query all_types($s: String, $i: I32, $big: I64, $u: U64, $f: F64, $b: Bool, \
+             $d: Date, $dt: DateTime, $blob: Blob, $opt: String?, $list: [I32], $vec: Vector(4)) \
+             { match { $x: User } return { $x.name } }",
+            true,
+            "all",
+        )])
+        .unwrap();
+        let entry = api::query_catalog_entry(reg.lookup("all_types").unwrap());
+        assert_eq!(entry.name, "all_types");
+        assert_eq!(entry.tool_name, "all");
+        assert!(!entry.mutation);
+
+        let by: std::collections::HashMap<_, _> =
+            entry.params.iter().map(|p| (p.name.as_str(), p)).collect();
+        assert_eq!(by["s"].kind, ParamKind::String);
+        assert_eq!(by["i"].kind, ParamKind::Int);
+        assert_eq!(by["big"].kind, ParamKind::BigInt, "I64 → bigint (string on the wire)");
+        assert_eq!(by["u"].kind, ParamKind::BigInt, "U64 → bigint");
+        assert_eq!(by["f"].kind, ParamKind::Float);
+        assert_eq!(by["b"].kind, ParamKind::Bool);
+        assert_eq!(by["d"].kind, ParamKind::Date);
+        assert_eq!(by["dt"].kind, ParamKind::DateTime);
+        assert_eq!(by["blob"].kind, ParamKind::Blob);
+        assert!(!by["s"].nullable);
+        assert!(by["opt"].nullable, "String? → nullable");
+        assert_eq!(by["list"].kind, ParamKind::List);
+        assert_eq!(by["list"].item_kind, Some(ParamKind::Int), "[I32] → list of int");
+        assert_eq!(by["vec"].kind, ParamKind::Vector);
+        assert_eq!(by["vec"].vector_dim, Some(4));
+    }
+
+    #[test]
+    fn catalog_entry_flags_mutation_and_empty_params() {
+        use crate::api;
+        let reg = QueryRegistry::from_specs(vec![spec(
+            "add_user",
+            "query add_user($name: String) { insert User { name: $name } }",
+            true,
+        )])
+        .unwrap();
+        let entry = api::query_catalog_entry(reg.lookup("add_user").unwrap());
+        assert!(entry.mutation, "insert body → mutation flag");
+
+        let reg2 = QueryRegistry::from_specs(vec![spec(
+            "no_params",
+            "query no_params() { match { $u: User } return { $u.name } }",
+            true,
+        )])
+        .unwrap();
+        let entry2 = api::query_catalog_entry(reg2.lookup("no_params").unwrap());
+        assert!(entry2.params.is_empty(), "no declared params → empty list");
+    }
 }

crates/omnigraph-server/tests/openapi.rs

@@ -168,6 +168,7 @@ const EXPECTED_PATHS: &[&str] = &[
     "/export",
     "/change",
     "/mutate",
+    "/queries",
     "/queries/{name}",
     "/schema",
     "/schema/apply",
@@ -702,6 +703,7 @@ fn protected_endpoints_reference_bearer_token_security() {
         ("/read", "post"),
         ("/change", "post"),
         ("/schema/apply", "post"),
+        ("/queries", "get"),
         ("/queries/{name}", "post"),
         ("/ingest", "post"),
         ("/export", "post"),

crates/omnigraph-server/tests/server.rs

@@ -415,6 +415,87 @@ async fn invoke_query_holder_without_read_sees_403_not_404() {
     assert_eq!(absent_status, StatusCode::NOT_FOUND, "unknown query still 404s");
 }
 
+fn get_request(uri: &str, token: &str) -> Request<Body> {
+    Request::builder()
+        .uri(uri)
+        .method(Method::GET)
+        .header("authorization", format!("Bearer {token}"))
+        .body(Body::empty())
+        .unwrap()
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn list_queries_returns_only_exposed_with_typed_params() {
+    let (_temp, app) = app_with_stored_queries(
+        &[
+            ("find_person", FIND_PERSON_GQ, true),
+            (
+                "add_person",
+                "query add_person($name: String) { insert Person { name: $name } }",
+                true,
+            ),
+            ("hidden", "query hidden() { match { $p: Person } return { $p.name } }", false),
+        ],
+        &[("act-invoke", "t-invoke")],
+        INVOKE_POLICY_YAML,
+    )
+    .await;
+    let (status, body) = json_response(&app, get_request("/queries", "t-invoke")).await;
+    assert_eq!(status, StatusCode::OK, "body: {body}");
+
+    let entries = body["queries"].as_array().unwrap();
+    let names: Vec<&str> = entries.iter().map(|q| q["name"].as_str().unwrap()).collect();
+    assert!(
+        names.contains(&"find_person") && names.contains(&"add_person"),
+        "exposed queries listed: {names:?}"
+    );
+    assert!(!names.contains(&"hidden"), "non-exposed query hidden from the catalog: {names:?}");
+
+    let fp = entries.iter().find(|q| q["name"] == "find_person").unwrap();
+    assert_eq!(fp["mutation"], false);
+    assert_eq!(fp["tool_name"], "find_person");
+    assert_eq!(fp["params"][0]["name"], "name");
+    assert_eq!(fp["params"][0]["kind"], "string");
+    let ap = entries.iter().find(|q| q["name"] == "add_person").unwrap();
+    assert_eq!(ap["mutation"], true, "stored insert → mutation");
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn list_queries_is_read_gated_so_a_non_invoker_can_list() {
+    // The catalog is read-gated (not invoke_query-gated), so a reader who
+    // lacks invoke_query still enumerates the exposed queries — the
+    // documented probe-oracle gap until per-query Cedar filtering lands.
+    let (_temp, app) = app_with_stored_queries(
+        &[("find_person", FIND_PERSON_GQ, true)],
+        &[("act-noinvoke", "t-noinvoke")],
+        INVOKE_POLICY_YAML,
+    )
+    .await;
+    let (status, body) = json_response(&app, get_request("/queries", "t-noinvoke")).await;
+    assert_eq!(status, StatusCode::OK, "read-gated catalog; body: {body}");
+    let names: Vec<&str> = body["queries"]
+        .as_array()
+        .unwrap()
+        .iter()
+        .map(|q| q["name"].as_str().unwrap())
+        .collect();
+    assert!(
+        names.contains(&"find_person"),
+        "a reader lists the catalog despite lacking invoke_query: {names:?}"
+    );
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn list_queries_is_empty_when_no_registry() {
+    let (_temp, app) = app_for_loaded_graph_with_auth("demo-token").await;
+    let (status, body) = json_response(&app, get_request("/queries", "demo-token")).await;
+    assert_eq!(status, StatusCode::OK, "body: {body}");
+    assert!(
+        body["queries"].as_array().unwrap().is_empty(),
+        "no stored-query registry → empty catalog"
+    );
+}
+
 fn drifted_test_schema() -> String {
     fs::read_to_string(fixture("test.pg"))
         .unwrap()

openapi.json

@@ -829,6 +829,53 @@
         ]
       }
     },
+    "/queries": {
+      "get": {
+        "tags": [
+          "queries"
+        ],
+        "summary": "List the graph's exposed stored queries as a typed tool catalog.",
+        "description": "Returns the `mcp.expose == true` subset of the `queries:` registry, each\nwith its MCP tool name, read/mutate flag, description/instruction, and\ntyped parameters — enough for a client to register them as tools without\nfetching `.gq` source. Read-gated; the catalog is graph-wide (branch\nindependent — `read` is authorized against `main`). **Not** Cedar-filtered\nper query yet, so it can list a query whose `invoke_query` the caller\nlacks (a known gap until per-query authorization lands).",
+        "operationId": "list_queries",
+        "responses": {
+          "200": {
+            "description": "Stored-query catalog (the mcp.expose subset, with typed params)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/QueriesCatalogOutput"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Unauthorized",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorOutput"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Forbidden",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorOutput"
+                }
+              }
+            }
+          }
+        },
+        "security": [
+          {
+            "bearer_token": []
+          }
+        ]
+      }
+    },
     "/queries/{name}": {
       "post": {
         "tags": [
@@ -1840,6 +1887,120 @@
           }
         }
       },
+      "ParamDescriptor": {
+        "type": "object",
+        "description": "One declared parameter of a stored query, projected for the catalog.",
+        "required": [
+          "name",
+          "kind",
+          "nullable"
+        ],
+        "properties": {
+          "item_kind": {
+            "oneOf": [
+              {
+                "type": "null"
+              },
+              {
+                "$ref": "#/components/schemas/ParamKind",
+                "description": "Element kind when `kind == list` (always a scalar — the grammar\nforbids lists of vectors or nested lists)."
+              }
+            ]
+          },
+          "kind": {
+            "$ref": "#/components/schemas/ParamKind"
+          },
+          "name": {
+            "type": "string"
+          },
+          "nullable": {
+            "type": "boolean",
+            "description": "`false` → the caller must supply it; `true` → optional."
+          },
+          "vector_dim": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "format": "int32",
+            "description": "Dimension when `kind == vector`.",
+            "minimum": 0
+          }
+        }
+      },
+      "ParamKind": {
+        "type": "string",
+        "description": "The kind of a stored-query parameter, decomposed so a client (e.g. an\nMCP server) can build a typed input schema with a closed `match` and\nnever re-parse omnigraph's type spelling. `bigint`/`date`/`datetime`/\n`blob` are carried as JSON strings on the wire: a 64-bit integer past\n2^53 loses precision as a JSON number, and Date/DateTime are ISO\nstrings, Blob a blob-URI string.",
+        "enum": [
+          "string",
+          "bool",
+          "int",
+          "bigint",
+          "float",
+          "date",
+          "datetime",
+          "blob",
+          "vector",
+          "list"
+        ]
+      },
+      "QueriesCatalogOutput": {
+        "type": "object",
+        "description": "Response for `GET /queries`: the `mcp.expose` subset of a graph's\nstored-query registry, each with typed parameters.",
+        "required": [
+          "queries"
+        ],
+        "properties": {
+          "queries": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/QueryCatalogEntry"
+            }
+          }
+        }
+      },
+      "QueryCatalogEntry": {
+        "type": "object",
+        "description": "One entry in the stored-query catalog (`GET /queries`).",
+        "required": [
+          "name",
+          "tool_name",
+          "mutation",
+          "params"
+        ],
+        "properties": {
+          "description": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "instruction": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "mutation": {
+            "type": "boolean",
+            "description": "`true` for a stored mutation → an MCP read-only hint of `false`."
+          },
+          "name": {
+            "type": "string",
+            "description": "Registry key / invoke path segment (`POST /queries/{name}`)."
+          },
+          "params": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ParamDescriptor"
+            }
+          },
+          "tool_name": {
+            "type": "string",
+            "description": "MCP tool id (the `tool_name` override, else `name`)."
+          }
+        }
+      },
       "QueryRequest": {
         "type": "object",
         "description": "Inline read-query request for `POST /query`.\n\nFriendlier-named alternative to [`ReadRequest`] for ad-hoc reads and\nAI-agent integration. Mutations are rejected with 400 — use `POST\n/mutate` (or its deprecated alias `POST /change`) for write queries.\nField names are deliberately short (`query`, `name`) to match the GQ\nkeyword and the CLI `-e` flag.",