What it does
The `completion/complete` method is a Client → Server request that powers type-ahead suggestion UIs. The client sends a `ref` object identifying either a prompt (`ref/prompt`) or a resource template (`ref/resource`), an `argument` object carrying the argument name and the partial string the user has typed so far, and an optional `context.arguments` map of already-resolved sibling arguments. The server processes the partial value — typically filtering an in-memory list, querying a database, or applying prefix logic — and returns a `completion` object containing `values` (an array of matching strings), an optional `total` count, and an optional `hasMore` boolean. \n\n Before the client may send this request, the server must have advertised the `completions` capability in its `ServerCapabilities` object during the `initialize` handshake. If the server omits `completions`, the client must not call `completion/complete`; doing so will result in a `-32601 Method not found` error. The `context.arguments` field is particularly important for dependent arguments — for example, a `city` argument whose valid values depend on an already-chosen `country`. Servers should inspect the context and narrow suggestions accordingly rather than ignoring it. \n\n The method is best-effort and latency-sensitive: it fires on every keystroke. Servers should respond quickly (ideally under 100 ms) and return at most 100 values per call — the spec hard-caps `values.length` at 100. If more candidates exist, set `hasMore: true` and optionally populate `total` so the UI can hint "showing 100 of 342 results". There is no pagination cursor; the client must re-query with a longer prefix to narrow results further. Servers do not need to guarantee stable ordering between calls, but clients should avoid cancelling and re-sending faster than they can receive responses or they risk reordering UI flicker.
When to use
When the host wants live suggestions while the user types.
When NOT to use
For free-form input — there's nothing to suggest.
Notes
Capability gate is mandatory
The server must include `"completions": {}` in its `ServerCapabilities` during `initialize`. Clients must check for this before calling `completion/complete`. A server that omits the capability but still handles the method is non-conformant; a client that calls without the capability being advertised should expect a `-32601 Method not found` error.
Hard cap of 100 values — set hasMore
The spec limits `completion.values` to at most 100 items per response. If your backing list has more matches, trim to 100 and set `completion.hasMore: true`. Optionally populate `completion.total` with the full count so the UI can display "showing 100 of N". There is no cursor or offset parameter — clients get a tighter prefix by typing more characters and re-querying.
Debounce aggressively on the client side
Because this method is called on every keystroke, clients should debounce requests (typically 150–250 ms). Without debouncing, a server under load may receive dozens of overlapping in-flight requests. If the server or transport does not support request cancellation, responses may arrive out of order; clients should discard responses whose `argument.value` no longer matches the current input.
Use context.arguments for dependent completions
When a prompt has multiple arguments and earlier ones affect the valid set for a later one (e.g., `city` depends on `country`), the client passes previously-resolved values in `context.arguments`. Servers should always read this field before filtering candidates. Ignoring it produces irrelevant suggestions and degrades UX. This field is optional on the wire but semantically required whenever ordering dependencies exist.
Error handling and graceful degradation
Besides `-32601` (method not found when capability is absent), servers may return `-32602` (invalid params) if the `ref` points to an unknown prompt or resource template name. Clients should treat any error response as a signal to show an empty suggestion list rather than surfacing an error to the user — completion failures are recoverable and should never block the user from typing freely.
Request parameters
| Name | Type | Purpose |
|---|---|---|
| ref | PromptReference | ResourceTemplateReference | What is being completed. |
| argument | { name, value } | Current partial input. |
| context | { arguments? }? | Previously-resolved arguments. |
Response fields
| Name | Type | Purpose |
|---|---|---|
| completion.values | string[] | Up to 100 suggestions. |
| completion.total | number? | Total candidate count. |
| completion.hasMore | boolean? | More available beyond values. |
Examples
Argument completion
{ "method": "completion/complete", "params": { "ref": { "type": "ref/prompt", "name": "plan_vacation" }, "argument": { "name": "destination", "value": "Bar" } } }Common mistakes
❌ Returning more than 100 values
✅ Trim to 100 and set hasMore:true.