MCP Argument Completion for Prompts and Resources

Argument completion

Argument completion lets an MCP client ask a server for suggested values while a user fills a prompt argument or resource-template variable. It is a discovery mechanism attached to a particular reference and argument, not a request to execute the prompt or read the resource.

The MCP completion specification dated 25 November 2025 defines one request method, completion/complete, for both cases. A server that implements it declares the completions capability during initialization. Clients must negotiate that capability rather than assume every server can return suggestions.

Completion adds work on both sides. The client may send requests as the value changes, while the server must search or calculate suitable candidates. The specification therefore says clients should debounce rapid requests and cache results where appropriate, while servers should rate-limit the method. No latency or request-rate benchmark is defined, so an implementation should measure its own handler instead of promising that completion will feel instantaneous.

The reference and argument form the lookup key

A completion request identifies what is being completed in two parts:

• ref identifies the prompt or resource template.
• argument contains the argument name and its current value.

For a prompt, ref.type is ref/prompt and ref.name identifies the prompt. For a resource template, ref.type is ref/resource and ref.uri identifies the URI template. The current value may be a partial string that the server uses when choosing candidates.

This pairing is essential. An argument called language, path, or environment can appear in several prompts or templates without sharing a value set. Because the request carries both the reference and argument, the server can return different suggestions for the same argument name in different contexts. Keying a completion cache only by argument name would discard that distinction; the reference and current value belong in the cache key as well.

Prompts or URI templates can also have arguments that depend on earlier choices. The optional context.arguments object carries already resolved argument names and values. If a prompt has language and framework arguments, for example, a framework lookup can be scoped by the selected language. The context remains advisory input to the completion handler: it does not turn earlier suggestions into trusted or validated values.

This request shape complements, but does not replace, defining and validating MCP prompt arguments. Completion answers which values may be useful to show now. The prompt implementation still decides which values it accepts when the client later retrieves the prompt.

Completion for prompt arguments

Under the MCP prompt specification dated 25 November 2025, a server advertises prompt definitions with names, optional descriptions, and optional argument lists. Each declared argument can provide a name, description, and required flag. A client retrieves the rendered messages separately with prompts/get, passing the selected arguments in that request.

Completion sits between discovery and retrieval. After discovering a prompt, the client can send completion/complete for one of its arguments and present the returned values in a menu, search box, command palette, or another interface. The protocol does not require a particular interface. It also does not require the client to choose a suggestion; completion values are candidates rather than an enum embedded in the prompt definition.

The separation matters for server-provided prompt templates. The prompt definition explains the available arguments, completion can make those arguments easier to fill, and prompts/get performs the actual prompt request. Supporting one stage does not remove the checks required at the next stage.

Completion for resource-template variables

The MCP resource specification dated 25 November 2025 distinguishes concrete resources from resource templates. Concrete resources have URIs that a client can pass to resources/read. Resource templates expose parameterized resources through URI templates and are discovered with resources/templates/list.

For completion, the client references the resource template URI and names the variable it is filling. A template such as file:///{path} can therefore receive a completion request for path with the user’s current partial value. A template with several variables can receive prior values through context.arguments, allowing the server to narrow later suggestions without changing the template itself.

The completion response does not create a resource, resolve the template on the server, or return resource contents. It supplies possible variable values. The client still has to form the concrete URI and make the appropriate resource request, and the server still has to validate that request and enforce access rules.

What the server returns

A successful response contains a completion object. Its required values field is an array of suggested strings ranked by relevance. A response can contain at most 100 values. The optional total reports the number of matches, while hasMore indicates whether additional matches exist.

Those fields support discovery without implying that the response is exhaustive. When hasMore is true, the visible values are only part of the result set. Even when it is false, the response says what the completion handler suggested for that request; it does not define every valid value accepted by the eventual prompt or resource operation. A value missing from the array is therefore not automatically invalid.

Clients should handle partial or missing results without blocking the underlying form. They should also treat standard JSON-RPC errors as completion failures, not as proof that the prompt or resource itself is unusable. The specification identifies invalid references, missing required request data, unsupported capability, and internal server errors as possible failure cases.

How suggestions appear is a client decision. One client may show a filtered dropdown as the user types, while another may expose no visible completion interface even though the server supports the method. That is one reason to check MCP client differences between an IDE and a desktop assistant before treating server support as evidence of a particular user experience.

Suggestions are not authorization or validation

A completion value means only that the server returned that string as a relevant suggestion in the supplied context. It never authorizes the value, grants access to a resource, or proves that a later request containing it is valid.

The distinction applies in both directions. The completion handler must validate its own inputs, control access to sensitive suggestions, and prevent information disclosure. The final prompt or resource handler must then validate the completed request independently. Reusing the completion result as an authorization decision would let a discovery response bypass the checks attached to the operation that actually retrieves data or produces messages.

Suggestions can also become stale between completion and use. A resource may change, an allowed value may disappear, or the user’s access may differ when the final request is handled. The protocol provides no reservation or authorization token in a completion result. The final operation remains the authority on whether the submitted arguments or URI are acceptable.

What to check next

When implementing completion, check the negotiated completions capability, preserve the full reference-and-argument context, and keep final validation in prompts/get or the resource handler. If a selected value later fails, inspect the final request separately using the site’s guide to debugging a failing MCP operation; a successful completion response establishes discovery only.