MCP is best known for tools, resources, and prompts. Those primitives let an AI agent take action, read context, and run reusable workflows. Completions sit one layer closer to the developer experience: they help clients suggest valid values before a request is sent.

If you have ever typed a command and seen suggested file paths, branch names, issue IDs, database tables, or prompt arguments, you already know the pattern. MCP completions bring that kind of autocomplete to agent clients in a protocol-shaped way.

The core idea

An MCP completion is a server-provided suggestion for a value the client is trying to fill in. The client asks the server, “Given this reference and this partial argument value, what are the likely valid options?” The server returns a ranked list of completion values.

That sounds small, but it changes how usable MCP servers feel. Instead of making a user remember exact identifiers, a client can ask the server for options. Instead of guessing whether a resource URI takes repo, branch, or path, the client can guide the user through the right value.

Completions do not execute a tool. They do not read arbitrary resources. They are support calls that make other MCP interactions easier to configure.

How MCP completions work

The client sends a completion/complete request to the server. The request includes two main pieces:

  1. A reference to the thing being completed, usually a prompt or resource template.
  2. The argument name and current partial value.

A simplified request can look like this:

{
  "method": "completion/complete",
  "params": {
    "ref": {
      "type": "ref/prompt",
      "name": "summarize_issue"
    },
    "argument": {
      "name": "issue_id",
      "value": "12"
    }
  }
}

The server responds with possible matches:

{
  "completion": {
    "values": ["123", "124", "129"],
    "total": 3,
    "hasMore": false
  }
}

A client can then render those values in an autocomplete menu. If the user picks 123, the prompt call can be filled with that issue ID. If more matches exist, the client can keep narrowing the request as the user types.

The same pattern works for resource templates. A GitHub-style MCP server might complete repository names. A docs server might complete package names. A database server might complete schema or table names. The server owns the domain knowledge, so the client does not have to hard-code it.

Why it matters for AI agents

Completions help both humans and agents avoid brittle guessing.

For humans, the benefit is obvious. A user should not need to memorize opaque IDs just to run an MCP prompt. If a prompt asks for a project key, completion can show known project keys. If a resource template asks for a file path, completion can suggest valid paths.

For agents, completions are a way to reduce malformed requests. Models often infer argument values from context. Sometimes they infer correctly. Sometimes they produce a near miss: the right repository with the wrong owner, the right ticket prefix with the wrong number, or a resource URI that almost matches the template. Completion gives the client a protocol-native way to ask the server for allowed values before sending the final request.

That matters more as MCP moves from local hobby servers to production workflows. A coding agent connected to five servers needs names, IDs, and paths to line up. Autocomplete is not just a nice interface detail. It is one of the ways you keep agent actions pointed at the right target.

Completions in practice

Imagine a team exposes an MCP server for internal runbooks. The server has a prompt called prepare_incident_summary with arguments for service, severity, and incident_id.

Without completions, the user has to know the exact service slug. Is it billing-api, payments, or payments-api? With completions, the client can ask the server as the user types:

{
  "method": "completion/complete",
  "params": {
    "ref": {
      "type": "ref/prompt",
      "name": "prepare_incident_summary"
    },
    "argument": {
      "name": "service",
      "value": "pay"
    }
  }
}

The server returns:

{
  "completion": {
    "values": ["payments-api", "payments-worker", "payouts-service"],
    "total": 3,
    "hasMore": false
  }
}

Now the user or agent can pick the right service and continue. The prompt still runs through the normal MCP prompt flow. Completion only helped fill the argument.

When to add completions to an MCP server

Add completions when arguments have a known set of valid values and those values are hard to remember. Good candidates include:

  • Repository names, branch names, and file paths
  • Issue IDs, ticket keys, and project slugs
  • Database schemas, tables, and column names
  • Environment names such as staging, preview, and production
  • Resource template parameters such as package names or document IDs

Do not add completions for every string field. Free-form values, long text inputs, and one-off natural language arguments do not need autocomplete. Completion is most useful where the server can return a short, meaningful list.

FAQ

Q: Are MCP completions the same as model text completion?

A: No. Model text completion generates language. MCP completion returns possible argument values from an MCP server so a client can help fill a request.

Q: Do completions call tools or change data?

A: No. A completion request should be treated as a support query. It suggests values. It should not modify external systems or run the final workflow.

Q: Should every MCP server implement completions?

A: Not necessarily. Servers with prompts, resource templates, or identifier-heavy workflows benefit most. A simple server with a few tools and plain text arguments may not need them.

Q: How do completions relate to resources and prompts?

A: Completions make resources and prompts easier to use. They help clients fill valid parameters before calling a prompt or resolving a resource template.