feat(core): add opt-in periodic ping for connection health monitoring

[travisbreaks]

Summary

• Adds pingIntervalMs option to ProtocolOptions that enables automatic periodic pings to verify the remote side is still responsive
• Implemented at the Protocol level so both Client and Server benefit
• Client starts periodic pings after successful initialization; Server starts after receiving the initialized notification
• Disabled by default (opt-in). Ping failures are reported via onerror without stopping the timer
• Timer uses unref() so it does not prevent clean Node.js process exit

Per the MCP specification: "Implementations SHOULD periodically issue pings to detect connection health" with "configurable frequency."

Usage

const client = new Client(
    { name: 'my-client', version: '1.0.0' },
    { pingIntervalMs: 30_000 } // ping every 30 seconds
);

client.onerror = (error) => {
    console.warn('Connection issue:', error.message);
};

await client.connect(transport);
// Periodic pings start automatically after initialization

Key design decisions

• Protocol-level implementation: both Client and Server can use periodic pings, since the spec says "implementations" (not just clients)
• Opt-in, not opt-out: existing behavior is unchanged; you must explicitly set pingIntervalMs to enable
• Ping timeout equals the interval: if a ping takes longer than one interval to respond, it fails with a timeout error rather than stacking up
• unref() on the timer: the periodic ping does not keep the Node.js process alive if all other work is done

Relationship to other PRs

This complements PR #1712 (host process watchdog for stdio orphan detection). That PR detects when the host process is gone at the OS level; this PR detects when the remote MCP peer is unresponsive at the protocol level.

Fixes #1000

Test plan

• should not send periodic pings when pingIntervalMs is not set (default behavior unchanged)
• should send periodic pings when pingIntervalMs is set and startPeriodicPing is called
• should stop periodic pings on close
• should report ping errors via onerror without stopping the timer
• should not start duplicate timers if startPeriodicPing is called multiple times
• should stop periodic pings when transport closes unexpectedly
• All 446 core tests pass
• All 386 integration tests pass
• Build succeeds
• Lint passes

Changeset

@modelcontextprotocol/core: minor, @modelcontextprotocol/client: minor, @modelcontextprotocol/server: minor

Co-Authored-By: Claude Opus 4.6 (1M context) noreply@anthropic.com

[changeset-bot]

🦋 Changeset detected

Latest commit: 51a9eae

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 6 packages

Name	Type
@modelcontextprotocol/core	Minor
@modelcontextprotocol/client	Minor
@modelcontextprotocol/server	Minor
@modelcontextprotocol/node	Major
@modelcontextprotocol/express	Major
@modelcontextprotocol/hono	Major

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

Open in StackBlitz

@modelcontextprotocol/client

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/client@1717

@modelcontextprotocol/server

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/server@1717

@modelcontextprotocol/express

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/express@1717

@modelcontextprotocol/hono

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/hono@1717

@modelcontextprotocol/node

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/node@1717

commit: 51a9eae