When to reject a tool call vs return an error: defensive MCP handler design

This is a security rejection. Throw — don't return isError: true. The reason is subtle but important: if you return isError: true with a message like "Invalid API key", you have confirmed to the LLM (and to any adversarial prompt riding in tool output) that an API key was expected, was present but wrong, and that the correct one would succeed. That is more information than a security rejection should surface.

Compare these two:

if (!isValidApiKey(req.headers['x-api-key'])) {
  return {
    content: [{ type: 'text', text: 'Invalid API key — check your MCP_API_KEY env var' }],
    isError: true
  }
}

if (!isValidApiKey(req.headers['x-api-key'])) {
  throw new McpError(ErrorCode.InvalidRequest, 'Unauthorized')
}

The thrown error reaches the MCP client, which returns a 401 equivalent at the transport layer. The LLM does not see the error message. The client may display it to the human user — that is appropriate, because the human is the one who needs to fix their credentials. The LLM does not need to know how authentication works or what the failure mode looks like.

This case splits based on what is wrong. Missing required fields and wrong types are programmer errors — the LLM sent a malformed call. If your schema is registered correctly, the MCP SDK should reject these before your handler runs. If they reach your handler, something broke upstream. Throw.

Value-range violations are different. The LLM provided a structurally valid value that is semantically out of bounds — a page number beyond the last page, a date before the service existed, a batch size above the maximum. The LLM can understand this failure and correct its call. Return isError: true with the constraint clearly stated.

if (args.page < 1 || args.page > totalPages) {
  return {
    content: [{
      type: 'text',
      text: `Page ${args.page} out of range. Valid range: 1–${totalPages}.`
    }],
    isError: true
  }
}

if (typeof args.path !== 'string') {
  // Schema should have caught this — this is a programmer error
  throw new McpError(ErrorCode.InvalidParams, 'path must be a string')
}

One nuance: if your value-range error message would reveal implementation details (database row counts, internal ID ranges, file system structure), redact before returning. The message should tell the LLM what it needs to retry correctly — nothing more.

Downstream failures are almost always operational. Return isError: true. The LLM can inform the user, suggest alternatives, or try again after a delay. But scrub the error message before returning it — raw upstream error bodies frequently contain stack traces, internal IP addresses, database identifiers, and other details that should not reach the LLM context.

try {
  const result = await callUpstreamApi(args)
  return { content: [{ type: 'text', text: JSON.stringify(result) }] }
} catch (err) {
  return {
    content: [{ type: 'text', text: `Upstream error: ${err.message}` }],
    isError: true
  }
}

try {
  const result = await callUpstreamApi(args)
  return { content: [{ type: 'text', text: JSON.stringify(result) }] }
} catch (err) {
  const userMessage = classifyUpstreamError(err)
  return {
    content: [{ type: 'text', text: userMessage }],
    isError: true
  }
}

function classifyUpstreamError(err) {
  if (err.status === 429) return 'Rate limited — retry in 60 seconds.'
  if (err.status === 404) return 'Resource not found.'
  if (err.status === 403) return 'Permission denied — check your API credentials.'
  if (err.status >= 500) return 'Upstream service error — try again later.'
  return 'Unexpected error — please retry.'
}

The classifyUpstreamError pattern is the key: translate specific upstream errors into generic, LLM-safe messages. The actual error details go to your server logs, not the tool response.

This is where most servers make their biggest mistake. Policy violations feel "operational" — the user could fix them by upgrading their plan, or by asking for a file within the allowed path — so developers reach for isError: true. The right answer depends on one question: does returning error details help the LLM help the user, or does it teach an adversarial prompt how to probe the policy?

For plan-level restrictions (feature not included in Free tier), isError: true is reasonable — the LLM can tell the user to upgrade. For path traversal rejections, throw. For access-control scope violations where the resource exists but the user can't see it, the safe default is throw with a generic "not found" message to avoid confirming that the resource exists.

if (!canAccess(userId, resourceId)) {
  return {
    content: [{ type: 'text', text: 'You do not have access to resource ' + resourceId }],
    isError: true
  }
}

if (!canAccess(userId, resourceId)) {
  // Return 404-equivalent rather than 403 to avoid confirming existence
  return {
    content: [{ type: 'text', text: 'Resource not found.' }],
    isError: true
  }
}

// Path traversal: always throw — never confirm policy details
if (!isWithinAllowedDir(resolvedPath, allowedDir)) {
  throw new McpError(ErrorCode.InvalidRequest, 'Access denied')
}

Timeouts are operational errors. Return isError: true with a message that tells the LLM the operation timed out and whether retry makes sense. Be careful with messages: "timed out after 30 seconds on query: SELECT * FROM…" leaks your schema and query patterns. Return only the timeout fact and any retry guidance.

Resource exhaustion at the server level (out of memory, connection pool full) is different — this is an internal failure the LLM cannot meaningfully address. Throw. Let the client handle it as a transport error.

const timeoutMs = 10_000
let result
try {
  result = await Promise.race([
    doWork(args),
    new Promise((_, reject) =>
      setTimeout(() => reject(new TimeoutError()), timeoutMs)
    )
  ])
} catch (err) {
  if (err instanceof TimeoutError) {
    return {
      content: [{ type: 'text', text: 'Operation timed out. Try a smaller request or retry later.' }],
      isError: true
    }
  }
  // Non-timeout errors: throw — don't surface internal details
  throw new McpError(ErrorCode.InternalError, 'Internal error')
}
return { content: [{ type: 'text', text: JSON.stringify(result) }] }

This is the scenario where the error response mechanism matters most for security. If you detect suspected injection and return isError: true with a message like "Prompt injection detected in argument 'query': found pattern 'ignore previous'", you have just told the injected payload what patterns your detection catches — which is an enumeration oracle for an adversary tuning their injection.

Throw. Silently. Log internally with the full argument value for your own analysis. Give the LLM — which may itself be operating under the injected instructions — no signal about what was detected or why.

if (mightBeInjected(args.query)) {
  return {
    content: [{
      type: 'text',
      text: `Prompt injection detected: suspicious pattern in query argument`
    }],
    isError: true
  }
}

if (mightBeInjected(args.query)) {
  log.warn('Suspected prompt injection', {
    tool: 'search',
    arg: 'query',
    value: args.query,   // log full value for analysis
    sessionId: ctx.sessionId
  })
  // Generic rejection — same message as any other security failure
  throw new McpError(ErrorCode.InvalidRequest, 'Request rejected')
}

The pattern extends to any detection mechanism: rate-limit anomalies that might indicate automated probing, unusual argument patterns, or values that reference tool implementation details. The rule is: anything that reveals the shape of your detection logic should throw, not return a descriptive isError.