MCPg - Production-grade PostgreSQL MCP Server

Overview Schema Source Related Servers Discussions Admin

Retrieve with context

retrieve_with_context

Read-only

Run pgvector k-NN search and expand each hit one hop through foreign keys, returning the matching row plus related parent and child records in one call.

Instructions

Context-packed k-NN retrieval (a one-shot RAG building block). Runs a pgvector k-NN against schema.table.embedding_column for a caller-supplied query_vector (no embedding model needed), then expands each hit one hop along foreign keys and returns the hit row + its related parent / child records in one object. Parents (when include_parents, default true) are the rows a hit references via outbound FKs; children (when include_children, default true) are rows referencing the hit via inbound FKs, capped at max_related (default 5) per FK. Limitations: 1 hop only; inbound (child) expansion is same-schema only. The embedding column is dropped from every returned row. Requires the vector extension. Returns available, dimension, detail, and hits (each with distance, row, and related — a list of fk_name/direction/related_schema/related_table/rows).

Example: retrieve_with_context(schema='public', table='docs', embedding_column='embedding', query_vector=[0.1, 0.2, 0.3], k=5)

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "schema": "<schema>",
      "table": "<table>",
      "embedding_column": "<embedding_column>",
      "query_vector": "<query_vector>"
    },
    "name": "retrieve_with_context"
  }
}

Input Schema

Name	Required	Description	Default
`k`	No
`table`	Yes
`metric`	No		l2
`schema`	Yes
`database`	No	Optional: a database id from list_databases, to target a configured secondary (read-only) database; omit for the primary. Database names that are not configured ids are rejected.
`max_related`	No
`query_vector`	Yes
`include_parents`	No
`embedding_column`	Yes
`include_children`	No

Output Schema

Name	Required	Description	Default
`hits`	Yes
`detail`	No
`available`	Yes
`dimension`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.8.4Nov 5, 2026

changedInput schema / properties / database / description

Previous value: -"Optional: target a configured secondary (read-only) database by name; omit for the primary. Call list_databases to see the configured ids."New value: +"Optional: a database id from list_databases, to target a configured secondary (read-only) database; omit for the primary. Database names that are not configured ids are rejected."

First observedv0.6.8Jul 6, 2026

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered; the description still adds real behavior: parents/children are on by default, child expansion is capped per FK by `max_related` (default 5), the embedding column is stripped from every returned row, and the vector extension is required. What is missing is any note on cost/performance of doing k-NN plus N+1 FK expansions, or error behavior when the extension is absent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core mechanism, then defaults, limitations, and return shape in a logical order, closing with a concrete call example. It is dense rather than padded, though the parenthetical default restatements and the return-shape sentence add length where the output schema already exists.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter tool with 10% schema coverage, the definition covers every decision an agent needs: what it retrieves, how expansion is bounded, what is stripped, and what environment must exist. Return values are described even though an output schema exists, which is redundant but not harmful.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 10% (just `database`), so the description must carry the load and largely does: it defines `query_vector` as caller-supplied with no embedding model, explains `include_parents`/`include_children` semantics and defaults, and defines `max_related` as a per-FK cap. Gaps remain for `metric` (default l2) and `k` (only shown in the example), which are undocumented in both schema and prose.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific mechanism and resource: a pgvector k-NN over `schema.table.embedding_column` for a caller-supplied vector, followed by one-hop FK expansion returning hit rows plus related parents/children. This is clearly distinguishable from sibling vector tools like `vector_search` or `cross_table_similarity`, which do not interleave relational expansion.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied rather than stated: 'a one-shot RAG building block' with 'no embedding model needed' signals when to reach for it, and two hard limitations (1 hop only, child expansion same-schema only) are given. However, it never names an alternative (e.g. `vector_search` for plain ANN without joins, or `cross_table_similarity`) nor states when not to use this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server