MCP Server Argument Completions — autocomplete for tool and prompt parameters

What completions enable

Argument completion bridges the gap between free-form parameter entry and validated input:

Clients that support completions typically trigger them when a parameter accepts a string and the user has typed at least one character. Clients that don't support completions simply skip the completion/complete request — your server continues to work correctly without them.

Declaring completion support

import { Server } from '@modelcontextprotocol/sdk/server/index.js';

const server = new Server(
  { name: 'my-mcp-server', version: '1.0.0' },
  {
    capabilities: {
      tools: { listChanged: true },
      completions: {} // declare completion support
    }
  }
);

Declaring completions: {} tells clients they can send completion/complete requests. If you declare it but your handler throws MethodNotFound, clients treat this as a protocol error. Either implement the handler or don't declare the capability.

Implementing the completion handler

import { CompleteRequestSchema } from '@modelcontextprotocol/sdk/types.js';

server.setRequestHandler(CompleteRequestSchema, async ({ params }) => {
  const ref = params.ref;       // { type: 'ref/tool', name: 'tool_name', argument: 'arg_name' }
                                // or { type: 'ref/prompt', name: 'prompt_name', argument: 'arg_name' }
  const partialValue = params.argument.value; // what the user has typed so far

  // Route by reference type and tool/prompt name
  if (ref.type === 'ref/tool') {
    return await completeTool(ref.name, ref.argument, partialValue);
  }

  if (ref.type === 'ref/prompt') {
    return await completePrompt(ref.name, ref.argument, partialValue);
  }

  return { completion: { values: [], hasMore: false } };
});

async function completeTool(
  toolName: string,
  argumentName: string,
  partial: string
): Promise<{ completion: { values: string[]; hasMore: boolean } }> {
  if (toolName === 'get_customer' && argumentName === 'customer_id') {
    return await completeCustomerId(partial);
  }

  if (toolName === 'update_order' && argumentName === 'order_id') {
    return await completeOrderId(partial);
  }

  if (toolName === 'assign_tag' && argumentName === 'tag_name') {
    return await completeTagName(partial);
  }

  // No completions for this tool/argument combination
  return { completion: { values: [], hasMore: false } };
}

Database-backed dynamic completions

const COMPLETION_LIMIT = 20;

async function completeCustomerId(partial: string): Promise<{
  completion: { values: string[]; hasMore: boolean }
}> {
  // Use a prefix-match query — keep the result tight
  const rows = await db.query(
    `SELECT id, name FROM customers
     WHERE id ILIKE $1 OR name ILIKE $1
     ORDER BY name ASC
     LIMIT $2`,
    [`${partial}%`, COMPLETION_LIMIT + 1] // fetch one extra to detect hasMore
  );

  const hasMore = rows.rowCount > COMPLETION_LIMIT;
  const values = rows.rows
    .slice(0, COMPLETION_LIMIT)
    // Format as 'id (name)' so the LLM/user has context when selecting
    .map(r => `${r.id} (${r.name})`);

  return { completion: { values, hasMore } };
}

async function completeTagName(partial: string): Promise<{
  completion: { values: string[]; hasMore: boolean }
}> {
  // Enum-style completions from a tags table
  const rows = await db.query(
    `SELECT name FROM tags
     WHERE name ILIKE $1
     ORDER BY usage_count DESC, name ASC
     LIMIT $2`,
    [`%${partial}%`, COMPLETION_LIMIT + 1]
  );

  const hasMore = rows.rowCount > COMPLETION_LIMIT;
  return {
    completion: {
      values: rows.rows.slice(0, COMPLETION_LIMIT).map(r => r.name),
      hasMore
    }
  };
}

Always index the columns you use in completion queries. A LIKE 'prefix%' query on an unindexed 10M-row table takes 2+ seconds — far outside the completion latency budget. For prefix matching on string IDs: CREATE INDEX ON customers(id text_pattern_ops). For full-text name matching: CREATE INDEX ON customers USING gin(to_tsvector('english', name)) or a simple trigram index with pg_trgm.

Completion for prompt arguments

async function completePrompt(
  promptName: string,
  argumentName: string,
  partial: string
): Promise<{ completion: { values: string[]; hasMore: boolean } }> {
  if (promptName === 'review_pull_request' && argumentName === 'pr_number') {
    // Suggest recent open PRs
    const prs = await github.pulls.list({
      owner, repo,
      state: 'open',
      per_page: 20
    });

    const matches = prs.data.filter(pr =>
      String(pr.number).startsWith(partial) ||
      pr.title.toLowerCase().includes(partial.toLowerCase())
    );

    return {
      completion: {
        values: matches.slice(0, 10).map(pr => `${pr.number} — ${pr.title}`),
        hasMore: matches.length > 10
      }
    };
  }

  if (promptName === 'review_pull_request' && argumentName === 'focus') {
    // Static enum completion — these don't change
    const options = ['security', 'performance', 'style', 'all'];
    const matches = options.filter(o => o.startsWith(partial.toLowerCase()));
    return { completion: { values: matches, hasMore: false } };
  }

  return { completion: { values: [], hasMore: false } };
}

Performance requirements

Completion responses must arrive within the client's keystroke debounce window — typically 150–300ms total round-trip. Server processing budget: under 100ms to leave margin for network latency. Three constraints follow from this:

1. No unindexed table scans. Every column in your completion WHERE clause must have an appropriate index. Test with EXPLAIN ANALYZE and confirm the query uses an index scan, not a sequential scan.
2. No external API calls. Don't call GitHub, Stripe, or any external API in a completion handler — the external API latency blows the budget. Cache the data you need for completions (a 30-second Redis cache of recent PRs works; staleness at that TTL is acceptable for autocomplete).
3. Limit result set size. Return at most 20–50 values. A dropdown with 100 items is slower to render and harder to navigate than one with 10. Rank by relevance (most recently used, highest usage count, closest string distance) and return the best matches.

// Add a p95 latency check to your health endpoint
app.get('/health/completions', async (req, res) => {
  const start = Date.now();
  try {
    await completeCustomerId('test');
    const latencyMs = Date.now() - start;
    const healthy = latencyMs < 100;
    res.status(healthy ? 200 : 503).json({
      status: healthy ? 'ok' : 'degraded',
      latency_ms: latencyMs,
      threshold_ms: 100
    });
  } catch (e) {
    res.status(503).json({ status: 'down', error: (e as Error).message });
  }
});

Testing completions

import { describe, it, expect } from 'vitest';
import { createTestClient } from './test-helpers.js';

describe('argument completions', () => {
  it('completes customer_id prefix', async () => {
    const client = await createTestClient();
    const result = await client.complete({
      ref: { type: 'ref/tool', name: 'get_customer', argument: 'customer_id' },
      argument: { value: 'cus_4' }
    });

    expect(result.completion.values.length).toBeGreaterThan(0);
    // All values should start with the prefix
    result.completion.values.forEach(v => {
      expect(v.toLowerCase()).toContain('cus_4');
    });
    // hasMore should be accurate
    if (result.completion.values.length === 20) {
      expect(typeof result.completion.hasMore).toBe('boolean');
    }
  });

  it('returns empty array for unknown tool', async () => {
    const client = await createTestClient();
    const result = await client.complete({
      ref: { type: 'ref/tool', name: 'nonexistent_tool', argument: 'some_param' },
      argument: { value: 'abc' }
    });

    expect(result.completion.values).toEqual([]);
    expect(result.completion.hasMore).toBe(false);
  });

  it('responds within 100ms', async () => {
    const client = await createTestClient();
    const start = Date.now();
    await client.complete({
      ref: { type: 'ref/tool', name: 'get_customer', argument: 'customer_id' },
      argument: { value: 'c' }
    });
    expect(Date.now() - start).toBeLessThan(100);
  });
});

Frequently asked questions

Further reading

• MCP Capabilities Negotiation — declaring completion support
• MCP Server Tool Discovery — writing argument descriptions that guide completion UX
• MCP Server Prompts — completing prompt arguments
• MCP Server Testing — integration tests for the completion handler
• MCP Server Caching — caching external API data for sub-100ms completions