spring-projects/spring-ai · error · IllegalArgumentException

Method cannot have more than one transport context parameter

Error message

Method cannot have more than one transport context parameter: {method} in {class}

What it means

Duplicate-parameter validation in AbstractMcpCompleteMethodCallback.validateParameters: an @McpComplete-annotated method declares more than one McpTransportContext parameter, which is ambiguous for argument binding; only one transport context parameter is allowed.

Source

Thrown at mcp/mcp-annotations/src/main/java/org/springframework/ai/mcp/annotation/method/complete/AbstractMcpCompleteMethodCallback.java:227

				}

				hasRequestContextParam = true;
			}
			else if (McpAsyncRequestContext.class.isAssignableFrom(paramType)) {
				if (hasRequestContextParam) {
					throw new IllegalArgumentException("Method cannot have more than one request context parameter: "
							+ method.getName() + " in " + method.getDeclaringClass().getName());
				}
				if (McpPredicates.isNotReactiveReturnType.test(method)) {
					throw new IllegalArgumentException(
							"Sync complete methods should use McpSyncRequestContext instead of McpAsyncRequestContext parameter: "
									+ method.getName() + " in " + method.getDeclaringClass().getName());
				}
				hasRequestContextParam = true;
			}
			else if (McpTransportContext.class.isAssignableFrom(paramType)) {
				if (hasTransportContext) {
					throw new IllegalArgumentException("Method cannot have more than one transport context parameter: "
							+ method.getName() + " in " + method.getDeclaringClass().getName());
				}
				hasTransportContext = true;
			}
			else if (isExchangeType(paramType)) {
				if (hasExchangeParam) {
					throw new IllegalArgumentException("Method cannot have more than one exchange parameter: "
							+ method.getName() + " in " + method.getDeclaringClass().getName());
				}
				hasExchangeParam = true;
			}
			else if (CompleteRequest.class.isAssignableFrom(paramType)) {
				if (hasRequestParam) {
					throw new IllegalArgumentException("Method cannot have more than one CompleteRequest parameter: "
							+ method.getName() + " in " + method.getDeclaringClass().getName());
				}
				hasRequestParam = true;
			}

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Remove the duplicate McpTransportContext parameter from the annotated method
2. Keep only one transport context parameter per completion method

Example fix

// before
public String complete(McpTransportContext t1, McpTransportContext t2, CompleteRequest req) { ... }
// after
public String complete(McpTransportContext transportContext, CompleteRequest req) { ... }

long t = Arrays.stream(m.getParameterTypes()).filter(McpTransportContext.class::isAssignableFrom).count();
if (t > 1) throw new IllegalStateException("Only one McpTransportContext parameter allowed: " + m);

try {
    callbackBuilder.build();
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("more than one transport context")) { /* drop duplicate param */ }
    throw e;
}

When it happens

Trigger: A method signature includes two parameters assignable to McpTransportContext.

Common situations: Adding a transport context to access transport-level info while an existing one is already present; copy-paste of method signatures.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Method cannot have more than one exchange parameter: {method
• Method cannot have more than one CompleteRequest parameter:
• Method cannot have more than one CompleteArgument parameter:
• Method cannot have more than one @McpProgressToken parameter
• Method cannot have more than one McpMeta parameter: {method}

AI-assisted analysis of spring-projects/spring-ai@98a7beda4f (2026-09-11). Data as JSON: /api/errors/b9853e17aaf78fae. Report an issue: GitHub.