- Home
- Skills
- Agents & Orchestration
- AI Agent SDK and MCP Breaking-Change Migration Playbook
More screenshots
Works with the AI Agents you already use
AI Agent SDK and MCP Breaking-Change Migration Playbook
**`@modelcontextprotocol/sdk` v1.x to v2.4+ Split (`@modelcontextprotocol/server` & `@modelcontextprotocol/client`):** - Rewrites imports for the v2 package split (`v2.4.0`).
$5
AI Agent SDK and MCP Breaking-Change Migration Playbook
Example session with this skill installed
Migrate our TypeScript MCP server and Vercel AI SDK agent from @modelcontextprotocol/sdk v1.12 (SSEServerTransport) and ai v5 (maxSteps + parameters) to @modelcontextprotocol/server v2.4.0 and ai v7.0.154.
- Read your context and instructions
- Compiled the ai agent sdk
Migration Plan Executed
-
Upgraded Dependencies in
package.json:- Replaced
@modelcontextprotocol/sdk(^1.12.0) with@modelcontextprotocol/server@2.4.0and@modelcontextprotocol/client@2.4.0. - Upgraded
aito7.0.154,@ai-sdk/openaito4.0.103, and added@ai-sdk/mcp@2.0.85.
- Replaced
-
Refactored
src/mcp-server.ts(v1 SSE -> v2.4.0 Streamable HTTP):
- import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
- import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
+ import crypto from "node:crypto";
+ import { McpServer, StreamableHTTPServerTransport } from "@modelcontextprotocol/server";
- server.tool("lookup_user", { userId: z.string() }, async ({ userId }) => ({
+ server.registerTool("lookup_user", {
+ title: "Lookup User",
+ description: "Fetch user record by ID",
+ inputSchema: z.object({ userId: z.string() }),
+ annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
+ }, async ({ userId }) => ({
content: [{ type: "text", text: JSON.stringify({ userId, active: true }) }]
}));
- app.get("/sse", async (req, res) => {
- transport = new SSEServerTransport("/messages", res);
- await server.connect(transport);
- });
+ const transport = new StreamableHTTPServerTransport({
+ sessionIdGenerator: () => crypto.randomUUID()
+ });
+ await server.connect(transport);
+ app.all("/mcp", async (req, res) => {
+ await transport.handleRequest(req, res, req.body);
+ });
- Refactored
src/agent.ts(Vercel AI SDK v5 -> v7.0.154):
- import { generateText, tool, experimental_createMCPClient } from "ai";
+ import { generateText, tool, stepCountIs } from "ai";
+ import { createMCPClient } from "@ai-sdk/mcp";
+ import { StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
- const mcpClient = await experimental_createMCPClient({ transport: { type: "sse", url } });
+ const mcpClient = await createMCPClient({ transport: new StreamableHTTPClientTransport(new URL(url)) });
const result = await generateText({
- model: openai("gpt-4o"),
- maxSteps: 5,
+ model: openai.responses("gpt-5"),
+ stopWhen: stepCountIs(5),
tools: {
...(await mcpClient.tools()),
pingHost: tool({
description: "Ping host",
- parameters: z.object({ host: z.string() }),
+ inputSchema: z.object({ host: z.string() }),
execute: async ({ host }) => ({ ok: true, host })
})
},
prompt: "Run diagnostics."
});
- Post-Migration Verification:
tsc --noEmit: Passed with 0 errors.- Verified
/mcpendpoint responds toinitializeandtools/listover Streamable HTTP.
Connects securely to your tools. The creator never sees your data.
About this skill
Ship Clean AI SDK & MCP Upgrades Without Hallucinated APIs
Most coding agents trained on 2024 or 2025 documentation still generate deprecated SSEServerTransport boilerplate, maxSteps in Vercel AI SDK, result_type in PydanticAI, or archived @modelcontextprotocol/server-* configs. AI Agent SDK and MCP Breaking-Change Migration Playbook gives your coding agent 7 battle-tested reference playbooks with exact before/after diffs, AST refactoring rules, and verification checklists for the biggest 2026 breaking changes.
What Is Inside (7 Complete Migration Playbooks)
@modelcontextprotocol/sdkv1.x to v2.4+ Split (@modelcontextprotocol/server&@modelcontextprotocol/client):- Rewrites imports for the v2 package split (
v2.4.0). - Migrates deprecated
SSEServerTransport/SSEClientTransportto single-endpointStreamableHTTPServerTransport/StreamableHTTPClientTransport. - Fixes v2.4.0 breaking wire changes: unwrapped
result.structuredContenton2025-11-25connections,z.int()enforcement onx-mcp-headerparameters (error-32020), and valid URI schemes on Ajv$id/$reffields. - Includes Python
mcp(v2.3.0) andfastmcp(v4.1.4) lifespan andstreamable-httpmigrations.
- Rewrites imports for the v2 package split (
- Archived
@modelcontextprotocol/server-*Replacements:- Exact
.mcp.jsonrewrites, environment variable mappings, and tool name translations forserver-github->https://api.githubcopilot.com/mcp/,server-puppeteer->@playwright/mcp@0.0.83,server-postgres->@bytebase/dbhub/@supabase/mcp-server-supabase@0.14.0,server-slack->@korotovsky/slack-mcp-server,server-brave-search->@brave/brave-search-mcp-server@2.1.4,server-filesystem@2.0.1(read_text_file),mcp-server-fetch==2026.10.24, andmcp-server-sqlite==2025.4.25(read_query/write_query).
- Exact
- OpenAI Node
v7.45.0& Pythonv3.39.0(Responses API):- Refactors legacy Chat Completions
functionsandbeta.chat.completions.parse(response_format) toclient.responses.createandclient.responses.parse(text_format/zodTextFormat). - Migrates removed
client.beta.threadsAssistants polling loops to statefulResponses APIcalls usingprevious_response_id.
- Refactors legacy Chat Completions
- Vercel AI SDK
aiv5/v6 tov7.0.154&@ai-sdk/mcpv2.0.85:- Converts
maxSteps: NtostopWhen: stepCountIs(N). - Updates
tool({ parameters })totool({ inputSchema })andtoolCall.args/toolResult.resulttotoolCall.input/toolResult.output. - Upgrades
experimental_createMCPClientto@ai-sdk/mcpcreateMCPClientwithStreamableHTTPClientTransport.
- Converts
@langchain/langgraphv1.5.3&@langchain/mcp-adaptersv2.0.1:- Converts legacy
StateGraph({ channels })definitions toAnnotation.Root({ ... })reducers. - Upgrades human-in-the-loop breakpoints to
interrupt()andnew Command({ resume }).
- Converts legacy
- Mistral
v3.3.0, PydanticAIv2.62.0, & Claude Agent SDKv0.3.311:- Updates
@mistralai/mistralaidefaultMistralClientimports to namedMistralclass and camelCase request fields. - Refactors
pydantic-airesult_type->output_type,result.data->result.output, and@agent.result_validator->@agent.output_validator. - Updates
@anthropic-ai/claude-agent-sdkquery()permissionMode/canUseToolcallbacks and multi-turnthinkingblock signature preservation.
- Updates
- Production
.mcp.jsonHardening Checklist:- Locks floating
@latesttags, configuresFASTMCP_LOG_LEVEL=ERRORto prevent stdio JSON-RPC framing corruption, enforces--read-onlydatabase flags, and verifiestools/listschema snapshots.
- Locks floating
Find more skills like this on the Claude Skills Marketplace, the Codex Skills Marketplace and the Gemini Skills Marketplace, or browse Claude Skills for Agents & Orchestration.
Does not support automatic migration of custom, non-standard MCP transport implementations. Requires existing type definitions for accurate symbol detection.
How to use
- 1
Connect your agent to the Agensi MCP
Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup
- 2
Sign in to Agensi
Your agent shows a sign-in link. Sign in and click Allow.
- 3
Ask for what you need
Your agent loads this skill and uses it on your task. It always asks before buying a skill.
Reviews
No reviews yet
Be one of the first to try it. Every listed skill goes through the trust checks below.
Security scanned
Checked by our 8-point scan before listing
Fresh listing
Recently published to Agensi
Money-back guarantee
Doesn't do what its page promises? You get your money back.
Trust & safety
Security scan
Security scan passed 20 days ago
- Software
PythonX Header MCP@playwright/mcp
Node.js@bytebase/dbhub@brave/brave-search-mcp-server@org/pkg
uv (Python tool runner)Chrome Devtools MCPFetch MCPAdapters MCP@org/mcp-server