MCP Argument Completion

MCP argument completion is autocomplete for the arguments of prompts and resource templates. As a user types a value, the client sends a completion/complete request with what they have typed so far. The server replies with up to 100 ranked suggestions, like an IDE's code completion.

Status in the 2026-07-28 spec: core (optional server utility). A server that offers it must declare the completions capability. It does not apply to tool arguments.

Completion is a small feature with a big effect on usability. Without it, users have to know exact IDs or names. This page is based on the 2026-07-28 Completion page, checked on 28 October 2026.

What completion is

The spec says servers can "offer autocompletion suggestions for the arguments of prompts and resource templates." When users fill in an argument for a prompt (identified by name) or a resource template (identified by URI), the server can suggest values.

There are two reference types:

Tools are not on that list. Tool arguments are filled in by the model using the tool's input schema. Completion is for humans filling in prompts and resource templates.

Why completion exists

Prompts and resource templates are user-facing. A user who runs a "review this repository" prompt may not remember the exact repository name. A template like orders://{orderId} is useless if nobody knows the IDs.

The spec frames completion as an IDE-style experience. Apps may show suggestions in a dropdown as users type, though the spec does not require any specific interface.

How it works

A basic request

The client sends completion/complete with the reference, the argument name and the current value. This is the spec's example:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "completion/complete",
  "params": {
    "ref": { "type": "ref/prompt", "name": "code_review" },
    "argument": { "name": "language", "value": "py" }
  }
}

The server replies:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "resultType": "complete",
    "completion": {
      "values": ["python", "pytorch", "pyside"],
      "total": 10,
      "hasMore": true
    }
  }
}

The rules for results:

• At most 100 values per response.
• Values ranked by relevance.
• total is optional and gives the full match count.
• hasMore says whether more results exist.

Using earlier answers

For prompts or templates with several arguments, clients should include earlier choices in context.arguments. In the spec's example, the user already chose python for language. A completion request for framework with the value fla then returns only flask.

That is useful for dependent fields. A "region" choice can narrow the "store" suggestions, for example.

Server and client duties

The spec lists what each side SHOULD do:

And four MUST rules for security. Implementations must validate all completion inputs, apply rate limiting, control access to sensitive suggestions, and prevent completion-based information disclosure.

That last rule matters. A completion endpoint that suggests customer names to anyone is a data leak, even if resources/read is locked down. Apply the same authorization to suggestions as to the data itself. The MCP security center covers related risks.

Errors

The spec suggests standard JSON-RPC errors:

• -32601 when the server does not support completion.
• -32602 for an invalid prompt name or missing required arguments.
• -32603 for internal errors.

What changed across spec versions

The 2026-07-28 changelog lists no completion-specific change. The differences come from protocol-wide updates, such as stateless requests.

One more detail: completion results are not on the list of results that must carry caching hints. The client-side "cache results where appropriate" advice is separate from the ttlMs system used for lists.

Common mistakes

1. Expecting completion for tool arguments. The spec covers prompts and resource templates only.
2. Forgetting the capability. Without completions, clients should not expect the method. Servers without it should return -32601.
3. Returning more than 100 values. Cap the list and set hasMore.
4. Suggesting data the user cannot access. That breaks the access-control and disclosure MUST rules.
5. No debounce on the client. Sending a request on every keystroke can trip the server's rate limit.

Next step

You have now covered tools, resources, prompts and completion. Browse the full MCP specification reference for the rest of the protocol, or talk to our MCP development team about building a server.

Frequently asked questions