MCP tools intermittently unavailable in onChatMessage

[Maxservais]

What I'm trying to do

Connect a Notion MCP server from an AIChatAgent and use the MCP tools in onChatMessage.

What happens

MCP tools are sometimes available and sometimes not. When they're missing, getAITools() returns an empty set with this warning:

[getAITools] WARNING: Reading tools from connection aik32tRf in state "connecting". Tools may not be loaded yet.

The connection finishes restoring after the response is already sent:

Chat message request
[getAITools] WARNING: Reading tools from connection aik32tRf in state "connecting". Tools may not be loaded yet.
Available tools: [ 'getWeatherInformation', 'getLocalTime', 'scheduleTask' ]
Connected successfully using streamable-http transport for https://mcp.notion.com/mcp
Discovery completed for https://mcp.notion.com/mcp
Chat message response

It seems like a race condition — sometimes the MCP connection is ready by the time onChatMessage runs, sometimes it isn't.

My code

async onChatMessage(
  onFinish: StreamTextOnFinishCallback<ToolSet>,
  options?: { abortSignal?: AbortSignal }
) {
  const mcpState = this.getMcpServers();
  const hasNotion = Object.values(mcpState.servers).some(
    (s) => s.name === "notion"
  );

  if (!hasNotion) {
    await this.addMcpServer("notion", "https://mcp.notion.com/mcp", {
      callbackHost: this._callbackHost
    });
  }

  await this.mcp.ensureJsonSchema();
  const mcpTools = this.mcp.getAITools(); // ← sometimes empty
  // ...
}

Versions

• agents@0.5.0
• @cloudflare/ai-chat@0.1.1

[threepointone]

Thank you for filing!

[threepointone]

Thanks for the detailed report - this is a confirmed race condition. When a Durable Object wakes from hibernation, MCP connections are restored in the background to avoid blocking the DO on slow or unresponsive servers. But this means the first message can be processed before those connections are ready, which is exactly what your logs show.

I'm considering a couple of approaches:

Option A: waitForMcpConnections config on AIChatAgent (leaning toward this)

An opt-in config so AIChatAgent waits for MCP connections to be ready before calling onChatMessage:

class MyAgent extends AIChatAgent {
  waitForMcpConnections = true; // or { timeout: 10_000 }
}

Simple, keeps the default non-blocking behavior for agents that don't use MCP tools.

Option B: Expose mcp.waitForConnections() API

A method you can call yourself wherever you need it:

async onChatMessage(onFinish, options) {
  await this.mcp.waitForConnections();
  const mcpTools = this.mcp.getAITools();
  // ...
}

More flexible, but requires you to know about it and call it in the right place.

I'm leaning toward A as the primary fix, possibly combined with B as a lower-level option for users working with the base Agent class.

As a workaround in the meantime, you can poll for readiness in your onChatMessage:

async onChatMessage(onFinish, options) {
  const deadline = Date.now() + 10_000;
  while (Date.now() < deadline) {
    const servers = this.getMcpServers();
    const allReady = Object.values(servers.servers).every(
      (s) => s.connectionState === "ready" || s.connectionState === "authenticating"
    );
    if (allReady) break;
    await new Promise((r) => setTimeout(r, 200));
  }

  const mcpTools = this.mcp.getAITools();
  // ...
}