Skip to main content
Glama
io.github.avaazquezz/mcp-qdrant

io.github.avaazquezz/mcp-qdrant

by avaazquezz

Upsert Qdrant points

qdrant_points_upsert
DestructiveIdempotent

Insert or replace points in a Qdrant collection using vectors or text plus payloads, with conditional insert-only, update-only, and filtered write modes.

Instructions

Insert or replace points (id + vector or text + payload) in a collection.

    `vector` matches the collection's vector config: a plain list for a
    single unnamed vector; a list of lists for an unnamed multivector;
    or a dict keyed by vector name for named vectors, where each value
    is a dense list, a multivector, or a sparse vector
    (`{"indices": [...], "values": [...]}`). Give `text` instead of `vector`
    to have it embedded with every model the collection declares (see
    `qdrant_collection_create`'s `text_model`) and stored in its text field
    — one text is one point, nothing is split. A text longer than the model
    reads (128 tokens, ~500 characters, for the multilingual MiniLM) is
    refused rather than silently cut: split it into several points. Needs
    the `embeddings` extra.

    `update_mode` makes the write conditional: `insert_only` never
    overwrites an existing id, `update_only` never creates a new one
    (default `upsert` does both). `update_filter` only overwrites existing
    points whose current payload matches the filter; ids that don't exist
    yet are inserted regardless (verified). `wait=false`
    returns before the write is applied.

    Fails with a clear error if the collection doesn't exist.

    Example: {"collection_name": "docs", "points": [
        {"id": 1, "vector": [0.1, 0.2, 0.3, 0.4], "payload": {"city": "ny"}}
    ]}
    Example (text): {"collection_name": "notes", "points": [
        {"id": 1, "text": "Grants for young people's housing", "payload": {"year": 2026}}
    ]}
    Example (named dense + sparse): {"collection_name": "docs", "points": [
        {"id": 1, "vector": {"dense": [0.1, 0.2, 0.3, 0.4],
            "sparse": {"indices": [1, 7], "values": [0.5, 0.2]}}}
    ]}
    

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": {
      "collection_name": "<collection_name>",
      "points": "<points>"
    },
    "name": "qdrant_points_upsert"
  }
}

Input Schema

NameRequiredDescriptionDefault
waitNo
pointsYes
update_modeNo
update_filterNo
collection_nameYes

Output Schema

NameRequiredDescriptionDefault
statusYes
operation_idNoSequential number of the operation

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed10 schema fields changedv2.12.0
    • changedInput schema / $defs / PointInput / description
      Previous value: -"A point to upsert: id + vector(s) + payload. See `PointVectorValue`\nfor the accepted vector shapes."New value: +"A point to upsert: id + payload + exactly one of `vector` (see\n`PointVectorValue` for the accepted shapes) or `text` (embedded with the\ncollection's declared models)."
    • removedInput schema / $defs / PointInput / properties / id / title
      Removed value: -"Id"
    • removedInput schema / $defs / PointInput / properties / payload / title
      Removed value: -"Payload"
    • addedInput schema / $defs / PointInput / properties / text
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null
      +}
    • changedInput schema / $defs / PointInput / properties / vector / anyOf
      Previous value: -[
      -  {
      -    "items": {
      -      "type": "number"
      -    },
      -    "type": "array"
      -  },
      -  {
      -    "items": {
      -      "items": {
      -        "type": "number"
      -      },
      -      "type": "array"
      -    },
      -    "type": "array"
      -  },
      -  {
      -    "additionalProperties": {
      -      "anyOf": [
      -        {
      -          "items": {
      -            "type": "number"
      -          },
      -          "type": "array"
      -        },
      -        {
      -          "$ref": "#/$defs/SparseVector"
      -        },
      -        {
      -          "items": {
      -            "items": {
      -              "type": "number"
      -            },
      -            "type": "array"
      -          },
      -          "type": "array"
      -        }
      -      ]
      -    },
      -    "type": "object"
      -  }
      -]New value: +[
      +  {
      +    "items": {
      +      "type": "number"
      +    },
      +    "type": "array"
      +  },
      +  {
      +    "items": {
      +      "items": {
      +        "type": "number"
      +      },
      +      "type": "array"
      +    },
      +    "type": "array"
      +  },
      +  {
      +    "additionalProperties": {
      +      "anyOf": [
      +        {
      +          "items": {
      +            "type": "number"
      +          },
      +          "type": "array"
      +        },
      +        {
      +          "$ref": "#/$defs/SparseVector"
      +        },
      +        {
      +          "items": {
      +            "items": {
      +              "type": "number"
      +            },
      +            "type": "array"
      +          },
      +          "type": "array"
      +        }
      +      ]
      +    },
      +    "type": "object"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • addedInput schema / $defs / PointInput / properties / vector / default
      Added value: +null
    • removedInput schema / $defs / PointInput / properties / vector / title
      Removed value: -"Vector"
    • changedInput schema / $defs / PointInput / required
      Previous value: -[
      -  "id",
      -  "vector"
      -]New value: +[
      +  "id"
      +]
    • removedInput schema / $defs / PointInput / title
      Removed value: -"PointInput"
    • changedInput schema / properties / update_filter / anyOf
      Previous value: -[
      -  {
      -    "additionalProperties": false,
      -    "description": "Qdrant payload filter. Combine conditions with `must` (all hold), `should` (any holds), `must_not` (none holds) or `min_should` ({conditions, min_count}); each takes a list of conditions or a single one. A condition is one of: {\"key\": k, \"match\": M} where M is exactly one of {\"value\": v}, {\"any\": [..]}, {\"except\": [..]}, {\"text\": s}, {\"text_any\": s}, {\"phrase\": s}, {\"prefix\": s}; {\"key\": k, \"range\": {\"lt\"|\"lte\"|\"gt\"|\"gte\": number or datetime}}; {\"key\": k, \"values_count\": {\"lt\"|\"lte\"|\"gt\"|\"gte\": n}}; {\"key\": k, \"geo_radius\": {\"center\": {\"lat\", \"lon\"}, \"radius\": meters}}; {\"key\": k, \"geo_bounding_box\": {\"top_left\", \"bottom_right\"}}; {\"key\": k, \"geo_polygon\": {\"exterior\", \"interiors\"}}; {\"is_empty\": {\"key\": k}}; {\"is_null\": {\"key\": k}}; {\"has_id\": [ids]}; {\"has_vector\": name}; {\"slice\": {\"total\": n, \"index\": i}}; {\"nested\": {\"key\": k, \"filter\": <filter>}}; or a nested filter. Keys for nested objects use dots (`a.b`); objects inside arrays use `a[].b`.",
      -    "properties": {
      -      "min_should": {
      -        "anyOf": [
      -          {
      -            "properties": {
      -              "conditions": {
      -                "items": {
      -                  "type": "object"
      -                },
      -                "type": "array"
      -              },
      -              "min_count": {
      -                "type": "integer"
      -              }
      -            },
      -            "required": [
      -              "conditions",
      -              "min_count"
      -            ],
      -            "type": "object"
      -          },
      -          {
      -            "type": "null"
      -          }
      -        ]
      -      },
      -      "must": {
      -        "anyOf": [
      -          {
      -            "anyOf": [
      -              {
      -                "items": {
      -                  "type": "object"
      -                },
      -                "type": "array"
      -              },
      -              {
      -                "type": "object"
      -              }
      -            ]
      -          },
      -          {
      -            "type": "null"
      -          }
      -        ]
      -      },
      -      "must_not": {
      -        "anyOf": [
      -          {
      -            "anyOf": [
      -              {
      -                "items": {
      -                  "type": "object"
      -                },
      -                "type": "array"
      -              },
      -              {
      -                "type": "object"
      -              }
      -            ]
      -          },
      -          {
      -            "type": "null"
      -          }
      -        ]
      -      },
      -      "should": {
      -        "anyOf": [
      -          {
      -            "anyOf": [
      -              {
      -                "items": {
      -                  "type": "object"
      -                },
      -                "type": "array"
      -              },
      -              {
      -                "type": "object"
      -              }
      -            ]
      -          },
      -          {
      -            "type": "null"
      -          }
      -        ]
      -      }
      -    },
      -    "type": "object"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "additionalProperties": false,
      +    "description": "Qdrant payload filter. Combine conditions with `must` (all hold), `should` (any holds), `must_not` (none holds) or `min_should` ({conditions, min_count}); each takes a list of conditions or a single one. A condition is one of: {\"key\": k, \"match\": M} where M is exactly one of {\"value\": v}, {\"any\": [..]}, {\"except\": [..]}, {\"text\": s}, {\"text_any\": s}, {\"phrase\": s}, {\"prefix\": s}, {\"substring\": s}; {\"key\": k, \"range\": {\"lt\"|\"lte\"|\"gt\"|\"gte\": number or datetime}}; {\"key\": k, \"values_count\": {\"lt\"|\"lte\"|\"gt\"|\"gte\": n}}; {\"key\": k, \"geo_radius\": {\"center\": {\"lat\", \"lon\"}, \"radius\": meters}}; {\"key\": k, \"geo_bounding_box\": {\"top_left\", \"bottom_right\"}}; {\"key\": k, \"geo_polygon\": {\"exterior\", \"interiors\"}}; {\"is_empty\": {\"key\": k}}; {\"is_null\": {\"key\": k}}; {\"has_id\": [ids]}; {\"has_vector\": name}; {\"slice\": {\"total\": n, \"index\": i}}; {\"nested\": {\"key\": k, \"filter\": <filter>}}; or a nested filter. Keys for nested objects use dots (`a.b`); objects inside arrays use `a[].b`.",
      +    "properties": {
      +      "min_should": {
      +        "anyOf": [
      +          {
      +            "properties": {
      +              "conditions": {
      +                "items": {
      +                  "type": "object"
      +                },
      +                "type": "array"
      +              },
      +              "min_count": {
      +                "type": "integer"
      +              }
      +            },
      +            "required": [
      +              "conditions",
      +              "min_count"
      +            ],
      +            "type": "object"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ]
      +      },
      +      "must": {
      +        "anyOf": [
      +          {
      +            "anyOf": [
      +              {
      +                "items": {
      +                  "type": "object"
      +                },
      +                "type": "array"
      +              },
      +              {
      +                "type": "object"
      +              }
      +            ]
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ]
      +      },
      +      "must_not": {
      +        "anyOf": [
      +          {
      +            "anyOf": [
      +              {
      +                "items": {
      +                  "type": "object"
      +                },
      +                "type": "array"
      +              },
      +              {
      +                "type": "object"
      +              }
      +            ]
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ]
      +      },
      +      "should": {
      +        "anyOf": [
      +          {
      +            "anyOf": [
      +              {
      +                "items": {
      +                  "type": "object"
      +                },
      +                "type": "array"
      +              },
      +              {
      +                "type": "object"
      +              }
      +            ]
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ]
      +      }
      +    },
      +    "type": "object"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
  2. Changed9 schema fields changedv2.6.0
    • addedInput schema / $defs / PointInput / additionalProperties
      Added value: +false
    • changedInput schema / $defs / PointInput / description
      Previous value: -"A point to upsert: a plain id + vector + payload — never `Document`,\n`Image`, or `InferenceObject` (qdrant-client's server-side embedding\ninference variants), which would contradict this server's principle of\nnever generating embeddings itself."New value: +"A point to upsert: id + vector(s) + payload. See `PointVectorValue`\nfor the accepted vector shapes."
    • addedInput schema / $defs / PointInput / properties / vector / anyOf
      Added value: +[
      +  {
      +    "items": {
      +      "type": "number"
      +    },
      +    "type": "array"
      +  },
      +  {
      +    "items": {
      +      "items": {
      +        "type": "number"
      +      },
      +      "type": "array"
      +    },
      +    "type": "array"
      +  },
      +  {
      +    "additionalProperties": {
      +      "anyOf": [
      +        {
      +          "items": {
      +            "type": "number"
      +          },
      +          "type": "array"
      +        },
      +        {
      +          "$ref": "#/$defs/SparseVector"
      +        },
      +        {
      +          "items": {
      +            "items": {
      +              "type": "number"
      +            },
      +            "type": "array"
      +          },
      +          "type": "array"
      +        }
      +      ]
      +    },
      +    "type": "object"
      +  }
      +]
    • removedInput schema / $defs / PointInput / properties / vector / items
      Removed value: -{
      -  "type": "number"
      -}
    • removedInput schema / $defs / PointInput / properties / vector / type
      Removed value: -"array"
    • addedInput schema / $defs / SparseVector
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "Sparse vector structure",
      +  "properties": {
      +    "indices": {
      +      "description": "Indices must be unique",
      +      "items": {
      +        "type": "integer"
      +      },
      +      "title": "Indices",
      +      "type": "array"
      +    },
      +    "values": {
      +      "description": "Values and indices must be the same length",
      +      "items": {
      +        "type": "number"
      +      },
      +      "title": "Values",
      +      "type": "array"
      +    }
      +  },
      +  "required": [
      +    "indices",
      +    "values"
      +  ],
      +  "title": "SparseVector",
      +  "type": "object"
      +}
    • addedInput schema / properties / update_filter
      Added value: +{
      +  "anyOf": [
      +    {
      +      "additionalProperties": false,
      +      "description": "Qdrant payload filter. Combine conditions with `must` (all hold), `should` (any holds), `must_not` (none holds) or `min_should` ({conditions, min_count}); each takes a list of conditions or a single one. A condition is one of: {\"key\": k, \"match\": M} where M is exactly one of {\"value\": v}, {\"any\": [..]}, {\"except\": [..]}, {\"text\": s}, {\"text_any\": s}, {\"phrase\": s}, {\"prefix\": s}; {\"key\": k, \"range\": {\"lt\"|\"lte\"|\"gt\"|\"gte\": number or datetime}}; {\"key\": k, \"values_count\": {\"lt\"|\"lte\"|\"gt\"|\"gte\": n}}; {\"key\": k, \"geo_radius\": {\"center\": {\"lat\", \"lon\"}, \"radius\": meters}}; {\"key\": k, \"geo_bounding_box\": {\"top_left\", \"bottom_right\"}}; {\"key\": k, \"geo_polygon\": {\"exterior\", \"interiors\"}}; {\"is_empty\": {\"key\": k}}; {\"is_null\": {\"key\": k}}; {\"has_id\": [ids]}; {\"has_vector\": name}; {\"slice\": {\"total\": n, \"index\": i}}; {\"nested\": {\"key\": k, \"filter\": <filter>}}; or a nested filter. Keys for nested objects use dots (`a.b`); objects inside arrays use `a[].b`.",
      +      "properties": {
      +        "min_should": {
      +          "anyOf": [
      +            {
      +              "properties": {
      +                "conditions": {
      +                  "items": {
      +                    "type": "object"
      +                  },
      +                  "type": "array"
      +                },
      +                "min_count": {
      +                  "type": "integer"
      +                }
      +              },
      +              "required": [
      +                "conditions",
      +                "min_count"
      +              ],
      +              "type": "object"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ]
      +        },
      +        "must": {
      +          "anyOf": [
      +            {
      +              "anyOf": [
      +                {
      +                  "items": {
      +                    "type": "object"
      +                  },
      +                  "type": "array"
      +                },
      +                {
      +                  "type": "object"
      +                }
      +              ]
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ]
      +        },
      +        "must_not": {
      +          "anyOf": [
      +            {
      +              "anyOf": [
      +                {
      +                  "items": {
      +                    "type": "object"
      +                  },
      +                  "type": "array"
      +                },
      +                {
      +                  "type": "object"
      +                }
      +              ]
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ]
      +        },
      +        "should": {
      +          "anyOf": [
      +            {
      +              "anyOf": [
      +                {
      +                  "items": {
      +                    "type": "object"
      +                  },
      +                  "type": "array"
      +                },
      +                {
      +                  "type": "object"
      +                }
      +              ]
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ]
      +        }
      +      },
      +      "type": "object"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null
      +}
    • addedInput schema / properties / update_mode
      Added value: +{
      +  "anyOf": [
      +    {
      +      "enum": [
      +        "upsert",
      +        "insert_only",
      +        "update_only"
      +      ],
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "title": "Update Mode"
      +}
    • addedInput schema / properties / wait
      Added value: +{
      +  "default": true,
      +  "title": "Wait",
      +  "type": "boolean"
      +}
  3. First observedv1.1.1

TDQS

A4.7/5.0
Behavior5/5

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

Annotations declare destructive/idempotent/openWorld but nothing operational; the description adds real behavioral detail: texts longer than the model window are refused rather than truncated, the `embeddings` extra is required for text mode, one text equals one point with no splitting, update_filter inserts non-matching new ids regardless (explicitly "verified"), wait=false returns before the write applies, and a missing collection fails with a clear error. That is exactly the kind of context annotations cannot convey.

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 purpose, then organized into vector/text, update-mode, failure, and example blocks — each section earns its place. It is long overall, and the three worked examples plus the re-statement of the default `upsert` add some bulk, but nothing is genuinely redundant for a tool with this many input shapes.

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?

An output schema exists, so return values need not be explained; the description instead covers everything an agent must decide before calling: shape of `vector` vs `text`, embedding-model constraint, conditional-write modes, filter semantics, wait behavior, and the missing-collection failure mode. Nothing material is left to inference.

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

Parameters5/5

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

Schema coverage is reported at 0%, so the description must carry the parameter burden and it does: it enumerates the three vector shapes (plain list, list of lists for multivectors, dict keyed by vector name with dense/multivector/sparse values), the sparse `{indices, values}` structure, the meaning of `text`, all three `update_mode` enum values, and the `update_filter` overwrite-versus-insert rule. Three concrete JSON examples further pin down the accepted forms.

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?

Opens with a specific verb+resource: "Insert or replace points (id + vector or text + payload) in a collection." The parenthetical immediately disambiguates the accepted point shapes, and the semantics (insert-or-replace, keyed by id) separate it cleanly from siblings like qdrant_points_get, qdrant_points_delete and qdrant_points_scroll even though those names are not cited.

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

Usage Guidelines4/5

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

Gives strong conditional guidance: use `text` instead of `vector` to have it embedded, `update_mode` insert_only vs update_only vs default upsert, `update_filter` only overwrites matching existing points, and `wait=false` returns early. What is missing is explicit sibling routing — it never says to use qdrant_points_delete to remove points or qdrant_query to search them — but the decision guidance for its own parameters is unusually clear.

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