What causes "MCP session must have client sampling capabilities" in eyaltoledano/claude-task-master?

Update/reconfigure the MCP client so its initialize request includes `capabilities: { sampling: {} }`.

MCP session must have client sampling capabilities

Error message

MCP session must have client sampling capabilities

What it means

After confirming an MCP session exists, the provider also requires the connected client to declare sampling capabilities (`session.clientCapabilities.sampling`). This error is thrown when the session is valid but the client never advertised sampling support, so the provider cannot delegate model calls to the client.

Source

Thrown at mcp-server/src/providers/mcp-provider.js:38

		return 'MCP_API_KEY';
	}

	isRequiredApiKey() {
		return false;
	}

	/**
	 * Override validateAuth to validate MCP session instead of API key
	 * @param {object} params - Parameters to validate
	 */
	validateAuth(params) {
		// Validate MCP session instead of API key
		if (!this.session) {
			throw new Error('MCP Provider requires active MCP session');
		}

		if (!this.session.clientCapabilities?.sampling) {
			throw new Error('MCP session must have client sampling capabilities');
		}
	}

	/**
	 * Creates and returns an MCP AI SDK client instance.
	 * @param {object} params - Parameters for client initialization
	 * @returns {Function} MCP AI SDK client function
	 * @throws {Error} If initialization fails
	 */
	getClient(params) {
		try {
			// Pass MCP session to AI SDK implementation
			return createMCP({
				session: this.session,
				defaultSettings: {
					temperature: params.temperature,
					maxTokens: params.maxTokens
				}

View on GitHub (pinned to c0c98d367c)

Solutions

Update/reconfigure the MCP client so its initialize request includes `capabilities: { sampling: {} }`.
Upgrade the client library if it predates MCP sampling support.
Use a server-side model provider (API key based) instead of client sampling when the client cannot sample.
Verify the capability object isn't being overwritten after initialization.

Example fix

// before
const client = await connect({ capabilities: {} }); // no sampling
// after
const client = await connect({ capabilities: { sampling: {} } });

Defensive patterns

Strategy: validation

Validate before calling

if (!client.getInfo?.().capabilities?.sampling) throw new Error('Client does not support MCP sampling');

Type guard

function supportsSampling(session) { return !!session?.clientCapabilities?.sampling; }

Try / catch

try { await provider.generate(params); } catch (e) { if (e.message.includes('sampling capabilities')) { fallbackToServerSideModel(); } else { throw e; } }

Prevention

Declare sampling capabilities in the client initialize request
Pin/upgrade client libraries that support MCP sampling
Document client requirements for consumers of your MCP server

When it happens

Trigger: An MCP client connects without `sampling` in its `clientCapabilities` during initialization, then the provider's validateAuth runs on a sampling-backed request.

Common situations: Using a minimal or older MCP client that doesn't implement the sampling capability; client initialized with capabilities explicitly omitting sampling; connecting through a proxy/bridge that drops capability declarations.

Related errors

AI-assisted analysis of eyaltoledano/claude-task-master@c0c98d367c (2026-08-29). Data as JSON: /api/errors/7b42354b5b5d8c91. Report an issue: GitHub.