Lesson 22 of 55: Claude Extended Thinking Mode With MCP Tools

Claude 3.7 Sonnet introduced extended thinking, a mode where the model spends additional compute on internal reasoning before producing its response. The current models, as of 20 October 2026, are Claude Opus 5.5 (claude-opus-5-5) and Claude Sonnet 5.5 (claude-sonnet-5-5). Their thinking is adaptive. The examples below use claude-opus-5-5. When combined with MCP tools, extended thinking transforms how the model approaches complex multi-step tasks: instead of immediately deciding to call a tool, Claude reasons through what it knows, what it needs, which tools would help, and what order to call them in. The result is dramatically fewer redundant tool calls and significantly better decisions on ambiguous tasks.

Claude extended thinking diagram showing internal reasoning loop before tool calls in dark minimal design
Extended thinking: Claude reasons internally before deciding to call tools – reducing noise, improving decisions.

Enabling Extended Thinking

Extended thinking is enabled by adding the thinking block to the API request. You control the “budget” – the maximum number of tokens Claude can use for internal reasoning. A higher budget allows deeper reasoning but adds latency and cost.

import Anthropic from '@anthropic-ai/sdk';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });

const mcpClient = new Client({ name: 'thinking-host', version: '1.0.0' }, { capabilities: {} });
await mcpClient.connect(new StdioClientTransport({ command: 'node', args: ['server.js'] }));
const { tools: mcpTools } = await mcpClient.listTools();
const claudeTools = mcpTools.map(t => ({ name: t.name, description: t.description, input_schema: t.inputSchema }));

async function runWithExtendedThinking(userMessage, thinkingBudget = 8000) {
  const messages = [{ role: 'user', content: userMessage }];

  while (true) {
    const response = await anthropic.messages.create({
      model: 'claude-opus-5-5',
      max_tokens: 16000,  // Must be > thinking budget
      thinking: {
        type: 'enabled',
        budget_tokens: thinkingBudget,  // Min: 1024, no hard max
      },
      tools: claudeTools,
      messages,
    });

    // Response may contain thinking blocks - they appear before text/tool_use
    const thinkingBlocks = response.content.filter(b => b.type === 'thinking');
    const textBlocks = response.content.filter(b => b.type === 'text');
    const toolUseBlocks = response.content.filter(b => b.type === 'tool_use');

    if (process.env.SHOW_THINKING) {
      for (const tb of thinkingBlocks) {
        console.error('\n[thinking]', tb.thinking.slice(0, 500) + '...');
      }
    }

    messages.push({ role: 'assistant', content: response.content });

    if (response.stop_reason === 'tool_use') {
      const toolResults = await Promise.all(
        toolUseBlocks.map(async (toolUse) => {
          const result = await mcpClient.callTool({
            name: toolUse.name,
            arguments: toolUse.input,
          });
          return { type: 'tool_result', tool_use_id: toolUse.id, content: result.content };
        })
      );
      messages.push({ role: 'user', content: toolResults });
    } else {
      return textBlocks.map(b => b.text).join('');
    }
  }
}

// Complex task: extended thinking shines here
const result = await runWithExtendedThinking(
  `I need to buy a laptop for machine learning research. 
   My budget is $2000. I prefer AMD GPUs but would consider NVIDIA. 
   It must have at least 32GB RAM expandable to 64GB, 
   and I work across Windows and Linux so driver support matters.
   Research and recommend the top 3 options.`,
  12000  // Higher budget for complex task
);

console.log(result);
await mcpClient.close();
Claude thinking budget dial showing trade-off between reasoning depth latency cost with task complexity axis dark
Choosing the thinking budget: simple tasks need 1,000-4,000 tokens; complex research tasks benefit from 8,000+.

When to Use Extended Thinking with MCP

Extended thinking is not free – it adds significant latency (often 10-30 seconds for high budgets) and substantial token cost. Use it selectively:

  • Use it for: complex research requiring 5+ tool calls, tasks requiring careful tradeoff analysis, situations where tool call order significantly affects outcome quality
  • Skip it for: simple lookups, single-tool tasks, time-sensitive queries, high-volume low-latency applications
// Adaptive thinking budget based on task complexity
function getThinkingBudget(task) {
  const wordCount = task.split(/\s+/).length;
  const hasComparisons = /compare|vs|versus|between|best|recommend/.test(task.toLowerCase());
  const hasMultipleRequirements = task.split(/and|also|additionally|plus/).length > 2;

  if (hasComparisons && hasMultipleRequirements) return 10000;
  if (hasComparisons || hasMultipleRequirements) return 5000;
  if (wordCount > 50) return 3000;
  return 0;  // No thinking for simple tasks
}

const budget = getThinkingBudget(userInput);
if (budget > 0) {
  return runWithExtendedThinking(userInput, budget);
} else {
  return runWithClaude(userInput); // Standard tool calling
}

“Extended thinking causes Claude to reason more thoroughly about tasks before responding, which can substantially improve performance on complex tasks. Thinking tokens are not cached and must be included in the context window when continuing a conversation.” – Anthropic Documentation, Extended Thinking

Failure Modes with Extended Thinking

Case 1: Setting max_tokens Less Than Thinking Budget

// WRONG: max_tokens must exceed budget_tokens
const response = await anthropic.messages.create({
  max_tokens: 4096,
  thinking: { type: 'enabled', budget_tokens: 8000 }, // 8000 > 4096 - API error!
});

// CORRECT: max_tokens must be greater than budget_tokens
const response = await anthropic.messages.create({
  max_tokens: 16000,
  thinking: { type: 'enabled', budget_tokens: 8000 }, // Valid: 16000 > 8000
});

Case 2: Not Passing Thinking Blocks Back in Continuation

// When continuing a conversation with extended thinking enabled,
// thinking blocks from previous turns MUST be included in the messages array.
// The SDK handles this automatically if you push the full response.content.
messages.push({ role: 'assistant', content: response.content }); // Include ALL blocks including thinking

What to Check Right Now

  • Test with SHOW_THINKING=1 – run your agent with thinking visible. Reading the thinking output reveals what the model understood about the task and why it chose each tool.
  • Measure latency impact – log response time with and without extended thinking on the same tasks. Quantify the tradeoff for your use case before deploying at scale.
  • Start with budget 4000-8000 – this range gives substantially improved reasoning for most tasks without the extreme latency of budgets above 15,000.
  • Use claude-sonnet-5-5 for anything where speed > accuracy – 3.5 Sonnet without thinking is typically faster and cheaper for tasks where the tradeoff makes sense.

nJoy πŸ˜‰

Claude Opus 5.5 and Sonnet 5.5 + MCP: Native Tool Calling

Claude’s tool use is the cleanest tool calling implementation in the major LLM providers. The API is symmetric: you send tools in the request, Claude returns tool_use blocks when it wants to call something, you run the tools, and you send back tool_result blocks. No function/tool naming confusion, no finish_reason gotchas – just a clear, typed message structure. This lesson builds the Claude + MCP integration from scratch, comparing it to the OpenAI pattern where they differ.

Claude tool use message format diagram showing tool-use block and tool-result block on dark background
Claude’s tool calling: tool_use blocks in assistant messages, tool_result blocks in user messages.

Claude Tool Use Format

Claude’s tool use has a fundamentally different message structure from OpenAI’s. The key difference: tool results go in a user message (not a separate role), nested inside a tool_result content block that references the tool use ID. This is more structured and less ambiguous than OpenAI’s approach.

// Claude tool calling message flow:

// 1. Request: tools defined, user message sent
// 2. Response: Claude returns tool_use block(s)
{
  role: 'assistant',
  content: [
    { type: 'text', text: 'Let me search for that.' },
    {
      type: 'tool_use',
      id: 'toolu_01XY',
      name: 'search_products',
      input: { query: 'wireless headphones', limit: 5 }
    }
  ]
}

// 3. You execute the tool through MCP
// 4. Send result back in a user message with tool_result block
{
  role: 'user',
  content: [{
    type: 'tool_result',
    tool_use_id: 'toolu_01XY',
    content: [{ type: 'text', text: 'Found 5 products: ...' }]
  }]
}

The Complete Claude + MCP Integration

import Anthropic from '@anthropic-ai/sdk';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });

const mcpClient = new Client({ name: 'claude-host', version: '1.0.0' }, { capabilities: {} });
await mcpClient.connect(new StdioClientTransport({ command: 'node', args: ['server.js'] }));

const { tools: mcpTools } = await mcpClient.listTools();

// Convert MCP tools to Anthropic format
const claudeTools = mcpTools.map(t => ({
  name: t.name,
  description: t.description,
  input_schema: t.inputSchema,  // Note: input_schema, not parameters
}));

async function runWithClaude(userMessage) {
  const messages = [{ role: 'user', content: userMessage }];

  while (true) {
    const response = await anthropic.messages.create({
      model: 'claude-sonnet-5-5',
      max_tokens: 4096,
      tools: claudeTools,
      messages,
    });

    // Append Claude's response to messages
    messages.push({ role: 'assistant', content: response.content });

    // If Claude stopped due to tool use, execute tools
    if (response.stop_reason === 'tool_use') {
      const toolUseBlocks = response.content.filter(b => b.type === 'tool_use');
      const toolResults = await Promise.all(
        toolUseBlocks.map(async (toolUse) => {
          console.error(`[tool] Calling: ${toolUse.name}`, toolUse.input);
          const result = await mcpClient.callTool({
            name: toolUse.name,
            arguments: toolUse.input,
          });

          return {
            type: 'tool_result',
            tool_use_id: toolUse.id,
            content: result.content,  // MCP content blocks work directly here
          };
        })
      );

      // Tool results go in a user message
      messages.push({ role: 'user', content: toolResults });

    } else {
      // end_turn or other stop reason - extract final text
      const finalText = response.content
        .filter(b => b.type === 'text')
        .map(b => b.text)
        .join('');

      return finalText;
    }
  }
}

const result = await runWithClaude('Compare the best noise-cancelling headphones under $300');
console.log(result);
await mcpClient.close();
Side by side comparison of Claude tool use format versus OpenAI function calling format showing differences dark
Claude vs OpenAI tool calling: the message structure differs but the underlying logic is the same.

Claude Opus 5.5, Sonnet 5.5, and Haiku 5.5 for Tool Use

As of 20 October 2026, Anthropic’s docs say to start with Claude Opus 5.5 (claude-opus-5-5) for most work, including agentic coding. Claude Sonnet 5.5 (claude-sonnet-5-5) is the faster, lower-cost model. Claude Haiku 5.5 (claude-haiku-5-5) is for high-volume, latency-sensitive tasks. All three support tool use.

// For fast, reliable tool calling:
model: 'claude-sonnet-5-5'

// For complex reasoning + tool use:
model: 'claude-opus-5-5'  // Includes extended thinking

// Haiku for high-volume, simple tool tasks:
model: 'claude-haiku-5-5'

“Claude is trained to use tools in the same way that humans do: by processing what it’s seen before and uses this context to craft appropriate tool calls or final responses. Tool use enables Claude to interact with external services and APIs in a structured way.” – Anthropic Documentation, Tool Use

Key Differences from OpenAI

Aspect Claude (Anthropic) GPT (OpenAI)
Tool result role user tool
Schema field input_schema parameters
Tool call detection stop_reason === 'tool_use' finish_reason === 'tool_calls'
Multiple tools All results in one user message Each result is a separate tool message
Tool call args toolUse.input (already parsed) JSON.parse(toolCall.function.arguments)

Failure Modes with Claude Tool Use

Case 1: Putting Tool Results in an Assistant Message

// WRONG: Tool results in wrong role
messages.push({ role: 'assistant', content: toolResults }); // API error

// CORRECT: Tool results go in user role
messages.push({ role: 'user', content: toolResults });

Case 2: Forgetting that Claude’s input Is Already Parsed JSON

// WRONG: Trying to JSON.parse Claude's tool input
const args = JSON.parse(toolUse.input); // Error: toolUse.input is already an object

// CORRECT: Use directly - Claude's SDK already parses it
const args = toolUse.input; // Already an object like { query: "...", limit: 5 }
await mcpClient.callTool({ name: toolUse.name, arguments: args });

What to Check Right Now

  • Test with a multi-tool Claude response – ask a question that forces 2-3 tool calls in one response. Verify all tool use blocks are collected and all results are bundled into one user message.
  • Verify input_schema not parameters – this is the single most common copy-paste error when moving from OpenAI to Claude code. Search your code for parameters in Claude tool definitions.
  • Handle vision content in tool results – Claude can process image content blocks in tool results. If your MCP tools return images (base64), pass them through as { type: 'image', source: ... } in the tool result content array.
  • Set a system prompt – Claude responds well to clear system prompts. Define the assistant’s persona, task scope, and output format at the system level.

nJoy πŸ˜‰

Lesson 20 of 55: Building a Production OpenAI Client for MCP Tool Loops

The gap between “demo that calls a tool” and “production client that handles 10,000 daily users” is everything we have not talked about yet: connection pooling, retry logic, cost control, token budget management, error classification, telemetry, and graceful degradation. This lesson builds a production-grade OpenAI MCP client library from scratch – the kind you would actually deploy in a company. Every pattern here comes from real production failure modes.

Production OpenAI MCP client architecture diagram showing connection pool retry logic telemetry dark
A production MCP client: connection management, retry, budget control, and telemetry baked in.

The Production Client Library

// mcp-openai-client.js - Production-grade MCP + OpenAI client

import OpenAI from 'openai';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const DEFAULT_CONFIG = {
  model: 'gpt-6-astra',
  maxTokens: 4096,
  maxIterations: 15,
  temperature: 0.1,
  retries: 3,
  retryDelay: 1000,  // ms
  budgetUSD: 0.50,   // Max cost per conversation
  timeoutMs: 120_000, // 2 minute timeout per conversation
};

// Token cost estimates (USD per 1M tokens, approximate)
// USD per 1M tokens, checked 20 October 2026. developers.openai.com/api/docs/models
const MODEL_COSTS = {
  'gpt-6-astra': { input: 10.00, output: 50.00 },
  'gpt-6.1-sol': { input: 2.00, output: 10.00 },
  'gpt-6-luna': { input: 0.10, output: 0.50 },
};

export class McpOpenAIClient {
  constructor(mcpServerConfig, options = {}) {
    this.config = { ...DEFAULT_CONFIG, ...options };
    this.openai = new OpenAI({ apiKey: options.apiKey || process.env.OPENAI_API_KEY });
    this.mcpServerConfig = mcpServerConfig;
    this.mcpClient = null;
    this.tools = [];
    this.totalCostUSD = 0;
  }

  async connect() {
    this.mcpClient = new Client(
      { name: 'production-host', version: '1.0.0' },
      { capabilities: {} }
    );

    const transport = new StdioClientTransport(this.mcpServerConfig);
    await this.mcpClient.connect(transport);

    const { tools } = await this.mcpClient.listTools();
    this.tools = tools.map(t => ({
      type: 'function',
      function: { name: t.name, description: t.description, parameters: t.inputSchema },
    }));

    console.error(`[mcp] Connected - ${this.tools.length} tools available`);
  }

  async disconnect() {
    await this.mcpClient?.close();
  }

  estimateCostUSD(inputTokens, outputTokens, model) {
    const costs = MODEL_COSTS[model] || MODEL_COSTS['gpt-6-astra'];
    return (inputTokens / 1_000_000) * costs.input + (outputTokens / 1_000_000) * costs.output;
  }

  async executeWithRetry(fn, maxRetries = this.config.retries) {
    let lastError;
    for (let attempt = 1; attempt <= maxRetries; attempt++) {
      try {
        return await fn();
      } catch (err) {
        lastError = err;
        const isRetryable = err.status === 429 || err.status === 500 || err.status === 503;
        if (!isRetryable || attempt === maxRetries) throw err;

        const delay = this.config.retryDelay * Math.pow(2, attempt - 1); // Exponential backoff
        console.error(`[openai] Attempt ${attempt} failed: ${err.message}. Retrying in ${delay}ms`);
        await new Promise(r => setTimeout(r, delay));
      }
    }
    throw lastError;
  }

  async run(userMessage, systemPrompt = null) {
    const startTime = Date.now();
    const messages = [];

    if (systemPrompt) messages.push({ role: 'system', content: systemPrompt });
    messages.push({ role: 'user', content: userMessage });

    let iteration = 0;
    let totalInputTokens = 0;
    let totalOutputTokens = 0;

    while (true) {
      if (++iteration > this.config.maxIterations) {
        throw new Error(`Exceeded max iterations (${this.config.maxIterations})`);
      }

      if (Date.now() - startTime > this.config.timeoutMs) {
        throw new Error(`Conversation timeout after ${this.config.timeoutMs}ms`);
      }

      if (this.totalCostUSD > this.config.budgetUSD) {
        throw new Error(`Budget exceeded: $${this.totalCostUSD.toFixed(4)} > $${this.config.budgetUSD}`);
      }

      const response = await this.executeWithRetry(() =>
        this.openai.chat.completions.create({
          model: this.config.model,
          messages,
          tools: this.tools.length > 0 ? this.tools : undefined,
          max_tokens: this.config.maxTokens,
          temperature: this.config.temperature,
        })
      );

      const usage = response.usage;
      totalInputTokens += usage?.prompt_tokens || 0;
      totalOutputTokens += usage?.completion_tokens || 0;
      const turnCost = this.estimateCostUSD(
        usage?.prompt_tokens || 0,
        usage?.completion_tokens || 0,
        this.config.model
      );
      this.totalCostUSD += turnCost;

      const choice = response.choices[0];
      const message = choice.message;
      messages.push(message);

      if (choice.finish_reason !== 'tool_calls') {
        const elapsedMs = Date.now() - startTime;
        console.error(`[stats] iterations=${iteration} tokens=${totalInputTokens}+${totalOutputTokens} cost=$${this.totalCostUSD.toFixed(4)} elapsed=${elapsedMs}ms`);
        return {
          content: message.content,
          iterations: iteration,
          totalCostUSD: this.totalCostUSD,
          tokens: { input: totalInputTokens, output: totalOutputTokens },
          elapsedMs,
        };
      }

      // Execute tool calls
      const toolResults = await Promise.all(
        message.tool_calls.map(async (tc) => {
          let args;
          try {
            args = JSON.parse(tc.function.arguments);
          } catch {
            return { role: 'tool', tool_call_id: tc.id, content: 'Error: Invalid tool arguments JSON' };
          }

          try {
            const result = await this.mcpClient.callTool({ name: tc.function.name, arguments: args });
            const text = result.content.filter(c => c.type === 'text').map(c => c.text).join('\n');
            const errorFlag = result.isError ? '[TOOL ERROR] ' : '';
            return { role: 'tool', tool_call_id: tc.id, content: errorFlag + text };
          } catch (err) {
            console.error(`[tool] ${tc.function.name} error: ${err.message}`);
            return { role: 'tool', tool_call_id: tc.id, content: `Tool execution failed: ${err.message}` };
          }
        })
      );

      messages.push(...toolResults);
    }
  }
}
OpenAI cost tracking dashboard showing per-model token costs budget control and usage metrics dark
Cost tracking: estimate cost per turn, accumulate per conversation, enforce budget limits before they hit your bill.

Usage Pattern

import { McpOpenAIClient } from './mcp-openai-client.js';

const client = new McpOpenAIClient(
  { command: 'node', args: ['server.js'] },
  {
    model: 'gpt-6-luna',
    budgetUSD: 0.10,
    maxIterations: 8,
    timeoutMs: 60_000,
  }
);

await client.connect();

const result = await client.run(
  'Find me a good Python book for beginners under $40',
  'You are a helpful book recommendation assistant.'
);

console.log('Answer:', result.content);
console.log('Cost:', `$${result.totalCostUSD.toFixed(4)}`);
console.log('Iterations:', result.iterations);

await client.disconnect();

“For production deployments, implement exponential backoff for rate limit errors (429). The OpenAI API will return Retry-After headers for rate limits – respect these values.” – OpenAI Documentation, Error Codes

Failure Modes in Production

Case 1: No Budget Control

// A single misbehaving agent with no budget cap can cost hundreds of dollars
// Always set a budgetUSD limit per conversation
// Always set a maxIterations limit per conversation
// Log and alert when conversations exceed 80% of budget

Case 2: Catching All Errors and Retrying Blindly

// Some errors should NOT be retried - e.g. 400 Bad Request (invalid schema)
// 429 = retry (rate limit)
// 500/503 = retry (server error)
// 400 = do NOT retry (your code is wrong)
// 401/403 = do NOT retry (authentication issue)

What to Check Right Now

  • Set per-conversation budgets – $0.10 is a reasonable starting point for most workflows. Adjust based on your model and expected tool call count.
  • Implement exponential backoff – the pattern shown above (doubling delay on each retry) is the industry standard. Start at 1000ms, cap at 60000ms.
  • Log every tool call – production debugging without tool call logs is nearly impossible. Log tool name, arguments, result length, and execution time for every call.
  • Monitor iteration counts – if average iterations are above 8, your tool descriptions or system prompt may be unclear. Investigate and improve before scaling.

nJoy πŸ˜‰

Lesson 19 of 55: OpenAI Responses API and Agents SDK With MCP

OpenAI released the Responses API and the Agents SDK as a unified approach to building agentic workflows. These are not just new API endpoints – they represent OpenAI’s opinionated view of how production agents should be structured. The Responses API replaces the Chat Completions API for agentic use cases. The Agents SDK wraps it with built-in MCP support, tool orchestration, and a pipeline abstraction that handles the looping automatically. This lesson shows you both layers and where MCP plugs in.

OpenAI Responses API and Agents SDK architecture diagram with MCP tool integration dark
The Agents SDK wraps the Responses API with built-in MCP support and automatic tool orchestration.

The Responses API

The Responses API (openai.responses.create()) is designed for stateful, multi-turn agentic sessions. Unlike Chat Completions which requires you to manage conversation history manually, the Responses API maintains state server-side via a response ID. You reference previous responses by ID, and the API handles context management including tool call history.

import OpenAI from 'openai';

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

// First turn - creates a new response
const response = await openai.responses.create({
  model: 'gpt-6-astra',
  input: 'Search for the best laptops under $1000',
  tools: openAITools,  // Same format as Chat Completions
});

const responseId = response.id;  // Save this for continuations

// Continue the conversation using the response ID (no need to re-send history)
const followUp = await openai.responses.create({
  model: 'gpt-6-astra',
  input: 'Now filter to only Dell and Lenovo models',
  previous_response_id: responseId,  // References prior context
  tools: openAITools,
});

“The Responses API is designed specifically for agentic workflows. It maintains conversation state server-side, supports native tool execution, and provides a unified interface for building multi-step AI tasks.” – OpenAI API Reference, Responses

The Agents SDK with MCP

The OpenAI Agents SDK (@openai/agents) provides a higher-level abstraction with native MCP support. Instead of writing the tool calling loop yourself, the SDK handles it automatically. You define an agent with tools and an instruction, and the SDK orchestrates the full pipeline.

import { Agent, run, MCPServerStdio } from '@openai/agents';

// Connect to your MCP server via the SDK's native MCP support
const mcpServer = new MCPServerStdio({
  name: 'my-tools',
  fullCommand: 'node ./my-mcp-server.js',
});

await mcpServer.connect();

// Protocol: 2025-11-25 (legacy host loop). SDK: @openai/agents.
// Status: excerpt. The Agents SDK attaches the server, it does not take listTools() as tools.
const agent = new Agent({
  name: 'Research Assistant',
  instructions: `You are a research assistant with access to product search and comparison tools.
    Always search for at least 3 options before recommending.
    Format your final recommendation as a clear list with prices.`,
  mcpServers: [mcpServer],
  model: 'gpt-6-astra',
});

// Run the agent - the SDK handles the tool calling loop
const result = await run(agent, 'Find the best wireless headphones under $200');
console.log('Final answer:', result.finalOutput);

// Clean up
await mcpServer.close();
OpenAI Agents SDK pipeline diagram showing Agent definition running with tools and MCP server integration dark
The Agents SDK pipeline: define agent + tools, run with input, SDK handles orchestration automatically.

Handoffs: Multi-Agent Patterns with the SDK

import { Agent, run, handoff } from '@openai/agents';

const searchAgent = new Agent({
  name: 'Search Specialist',
  instructions: 'You specialise in searching and retrieving product data.',
  tools: searchMcpTools,
  model: 'gpt-6-luna',  // Cheaper model for search
});

const analysisAgent = new Agent({
  name: 'Analysis Specialist',
  instructions: 'You specialise in comparing and recommending products based on data.',
  tools: analysisMcpTools,
  model: 'gpt-6-astra',        // Smarter model for complex reasoning
  handoffs: [handoff(searchAgent, 'Use search specialist when you need more data')],
});

const result = await run(analysisAgent, 'Compare the top 5 gaming laptops');
console.log(result.finalOutput);

Failure Modes with the Responses API and Agents SDK

Case 1: Not Handling Tool Call Errors in the Responses API

// The Responses API may return partial results if a tool fails
// Always check response.status and handle incomplete states
const response = await openai.responses.create({ ... });

if (response.status === 'incomplete') {
  console.error('Response incomplete:', response.incomplete_details);
  // Handle: retry, use partial output, or escalate
}

Case 2: State Leakage Between Responses API Sessions

// previous_response_id links responses in a chain
// If you reuse an ID from a different user's session, state leaks
// Always scope response IDs to the authenticated user's session store

const userSession = sessions.get(userId);
const response = await openai.responses.create({
  previous_response_id: userSession.lastResponseId || undefined,
  ...
});
userSession.lastResponseId = response.id;

What to Check Right Now

  • Try the Agents SDK first – if you are building a new agent, start with the Agents SDK. The automatic tool loop saves significant boilerplate.
  • Use the Responses API for long sessions – for multi-turn conversations with many tool calls, the Responses API’s server-side state management avoids sending large context windows repeatedly.
  • Test handoff behaviour – if using multi-agent handoffs, test the edge case where the receiving agent decides it does not need to hand off again and loops back incorrectly.
  • Check the Agents SDK version – the SDK is actively developed. Pin the version in package.json and read the changelog when upgrading: npm install @openai/agents.

nJoy πŸ˜‰

Lesson 18 of 55: OpenAI Streaming and Structured Outputs With MCP Tools

Tool calling with a single round-trip response is the entry point. But production MCP applications need streaming – the ability to show intermediate results to users as the model thinks – and structured outputs, which guarantee that the model’s final answer conforms to a schema you define. This lesson adds both to your OpenAI + MCP integration, covering the streaming tool call parsing mechanics and the structured output patterns that prevent hallucinated schemas in production.

OpenAI streaming tool calling diagram showing chunks arriving over time with tool call delta parsing dark
Streaming + tool calling: deltas arrive incrementally, tool call arguments accumulate, execution happens when complete.

Streaming with Tool Calls

When you stream a completion that includes tool calls, the tool call arguments arrive incrementally as delta chunks. You must accumulate them before you can parse and execute the tool. The pattern is: buffer all deltas, detect when a tool call is complete, then execute through MCP.

import OpenAI from 'openai';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
const mcpClient = new Client({ name: 'streaming-host', version: '1.0.0' }, { capabilities: {} });

await mcpClient.connect(new StdioClientTransport({ command: 'node', args: ['server.js'] }));
const { tools: mcpTools } = await mcpClient.listTools();

const openAITools = mcpTools.map(t => ({
  type: 'function',
  function: { name: t.name, description: t.description, parameters: t.inputSchema },
}));

async function runStreamingWithTools(userMessage) {
  const messages = [{ role: 'user', content: userMessage }];

  while (true) {
    // Stream the completion
    const stream = await openai.chat.completions.create({
      model: 'gpt-6-astra',
      messages,
      tools: openAITools,
      stream: true,
    });

    // Accumulate the full response
    let assistantMessage = { role: 'assistant', content: '', tool_calls: [] };
    const toolCallMap = {}; // index -> accumulated tool call

    for await (const chunk of stream) {
      const delta = chunk.choices[0]?.delta;
      if (!delta) continue;

      // Stream text content to UI
      if (delta.content) {
        assistantMessage.content += delta.content;
        process.stdout.write(delta.content); // Real-time output
      }

      // Accumulate tool call deltas
      if (delta.tool_calls) {
        for (const tcDelta of delta.tool_calls) {
          const idx = tcDelta.index;
          if (!toolCallMap[idx]) {
            toolCallMap[idx] = { id: '', type: 'function', function: { name: '', arguments: '' } };
          }
          const tc = toolCallMap[idx];
          if (tcDelta.id) tc.id += tcDelta.id;
          if (tcDelta.function?.name) tc.function.name += tcDelta.function.name;
          if (tcDelta.function?.arguments) tc.function.arguments += tcDelta.function.arguments;
        }
      }
    }

    assistantMessage.tool_calls = Object.values(toolCallMap);
    messages.push(assistantMessage);

    // No tool calls = we have the final answer
    if (assistantMessage.tool_calls.length === 0) {
      return assistantMessage.content;
    }

    // Execute all accumulated tool calls through MCP
    const toolResults = await Promise.all(
      assistantMessage.tool_calls.map(async (tc) => {
        const args = JSON.parse(tc.function.arguments);
        console.error(`\n[tool] Calling: ${tc.function.name}`);
        const result = await mcpClient.callTool({ name: tc.function.name, arguments: args });
        const text = result.content.filter(c => c.type === 'text').map(c => c.text).join('\n');
        return { role: 'tool', tool_call_id: tc.id, content: text };
      })
    );

    messages.push(...toolResults);
  }
}

const answer = await runStreamingWithTools('What are the best products under $50?');
console.log('\n\nFinal:', answer);
OpenAI structured output schema enforcement showing response json conforming to zod schema dark
Structured outputs: the model is forced to return JSON that matches your exact schema – no hallucinated fields.

Structured Outputs with MCP Tool Results

OpenAI’s structured outputs feature forces the model to return JSON that exactly matches a schema you specify. This is different from JSON mode (which just returns valid JSON) – structured outputs guarantee that every required field is present and every value is the correct type. You can use structured outputs for the final answer even when intermediate steps use tool calls.

import { z } from 'zod';
import { zodResponseFormat } from 'openai/helpers/zod.js';

// Define the schema for the final answer
const ProductRecommendationSchema = z.object({
  recommendations: z.array(z.object({
    product_name: z.string(),
    price: z.number(),
    reason: z.string(),
    confidence: z.enum(['high', 'medium', 'low']),
  })),
  total_products_checked: z.number(),
  search_strategy: z.string(),
});

// Use structured output for the final response
const finalResponse = await openai.beta.chat.completions.parse({
  model: 'gpt-6-astra',
  messages: [
    ...conversationHistory,
    { role: 'user', content: 'Based on the search results, provide your top 3 recommendations.' },
  ],
  response_format: zodResponseFormat(ProductRecommendationSchema, 'product_recommendations'),
});

const recommendations = finalResponse.choices[0].message.parsed;
// recommendations is now typed as ProductRecommendation - guaranteed to match schema
console.log(recommendations.recommendations[0].product_name);

“Structured Outputs is a feature that ensures the model will always generate responses that adhere to your supplied JSON Schema, so you don’t need to worry about the model omitting a required key, or hallucinating an invalid enum value.” – OpenAI Documentation, Structured Outputs

Failure Modes with Streaming Tool Calls

Case 1: Parsing Arguments Before All Deltas Arrive

// WRONG: Parsing tool call arguments during streaming
for await (const chunk of stream) {
  const delta = chunk.choices[0]?.delta;
  if (delta.tool_calls?.[0]?.function?.arguments) {
    const args = JSON.parse(delta.tool_calls[0].function.arguments); // WRONG - may be partial JSON
    await mcpClient.callTool({ ... });
  }
}

// CORRECT: Accumulate all deltas first, then parse
// (As shown in the complete streaming loop above)

Case 2: Missing tool_call_id in Tool Result Messages

// WRONG: tool_call_id missing or mismatched
messages.push({ role: 'tool', content: result }); // Missing tool_call_id

// CORRECT: Each tool result must include the exact tool_call_id
messages.push({ role: 'tool', tool_call_id: tc.id, content: result });

What to Check Right Now

  • Test streaming with a multi-tool query – ask a question that forces two tool calls in sequence. Verify the streaming output is coherent and the final answer is correct.
  • Add a progress indicator – during streaming, show a spinner or partial text. Users should see something happening, not a blank screen for 10 seconds.
  • Use structured outputs for all final answers – wherever your application needs to parse the model’s response programmatically, use structured outputs. It eliminates an entire class of parsing bugs.
  • Handle stream errors – wrap the for await (const chunk of stream) loop in a try-catch. Network errors during streaming are common and need graceful handling.

nJoy πŸ˜‰

OpenAI + MCP: Tool Calling with GPT-6 Astra, Sol, and Luna

OpenAI’s tool calling is where MCP integration becomes immediately tangible. You have an MCP server with tools registered on it. You have a GPT-6 Astra or GPT-6 Astra model that needs to use those tools. The integration is three steps: list tools from MCP, convert them to OpenAI’s function format, run the completion loop. This lesson builds that integration from scratch, explains every conversion step, and covers the failure modes that will break your agent in the middle of a production run.

OpenAI GPT-6 Astra connected to MCP server via tool calling loop diagram dark technical
OpenAI + MCP: the tool calling loop – list tools, generate, route tool calls to MCP, feed results back.

The OpenAI Tool Calling Model

OpenAI’s tool calling (formerly function calling) works by providing the model with a list of functions it can invoke. When the model decides to use a tool, the API returns a response with tool_calls instead of content. Your application executes the tool, then appends the result to the conversation and calls the API again. This loop continues until the model returns content with no pending tool calls.

MCP tools map cleanly onto OpenAI’s function schema. The conversion is mechanical: take the MCP tool’s name, description, and JSON Schema, and wrap them in OpenAI’s format.

// MCP tool schema (what the MCP server provides)
// {
//   name: "search_products",
//   description: "Search the product catalogue",
//   inputSchema: {
//     type: "object",
//     properties: {
//       query: { type: "string", description: "Search terms" },
//       limit: { type: "number", description: "Max results" }
//     },
//     required: ["query"]
//   }
// }

// OpenAI tool format (what openai.chat.completions.create() expects)
function mcpToolToOpenAITool(mcpTool) {
  return {
    type: 'function',
    function: {
      name: mcpTool.name,
      description: mcpTool.description,
      parameters: mcpTool.inputSchema,  // Direct pass-through - formats are compatible
    },
  };
}

“Tool calls allow models to call user-defined tools. Tools are specified in the request by the user, and the model can call them during message generation.” – OpenAI Documentation, Function Calling

The Complete Integration: MCP Client + OpenAI Loop

// mcp-openai-host.js
import OpenAI from 'openai';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

// Step 1: Connect to MCP server
const mcpClient = new Client(
  { name: 'openai-host', version: '1.0.0' },
  { capabilities: {} }
);

const transport = new StdioClientTransport({
  command: 'node',
  args: ['./my-mcp-server.js'],
  env: process.env,
});

await mcpClient.connect(transport);

// Step 2: Discover tools and convert to OpenAI format
const { tools: mcpTools } = await mcpClient.listTools();
const openAITools = mcpTools.map(tool => ({
  type: 'function',
  function: {
    name: tool.name,
    description: tool.description,
    parameters: tool.inputSchema,
  },
}));

console.log(`Loaded ${openAITools.length} tools from MCP server`);

// Step 3: Build the tool-calling loop
async function runWithTools(userMessage) {
  const messages = [{ role: 'user', content: userMessage }];

  while (true) {
    const response = await openai.chat.completions.create({
      model: 'gpt-6-astra',
      messages,
      tools: openAITools,
      tool_choice: 'auto',  // Let the model decide
    });

    const choice = response.choices[0];
    const message = choice.message;

    // Append the assistant message to conversation
    messages.push(message);

    // If no tool calls, we have the final answer
    if (choice.finish_reason !== 'tool_calls') {
      return message.content;
    }

    // Execute each tool call through MCP
    const toolResults = await Promise.all(
      message.tool_calls.map(async (toolCall) => {
        const args = JSON.parse(toolCall.function.arguments);

        console.log(`Calling tool: ${toolCall.function.name}`, args);

        const result = await mcpClient.callTool({
          name: toolCall.function.name,
          arguments: args,
        });

        // Format result for OpenAI
        const resultText = result.content
          .filter(c => c.type === 'text')
          .map(c => c.text)
          .join('\n');

        return {
          role: 'tool',
          tool_call_id: toolCall.id,
          content: resultText,
        };
      })
    );

    // Append all tool results to conversation
    messages.push(...toolResults);
    // Loop back to get the model's response to the tool results
  }
}

// Run it
const answer = await runWithTools('Find the top 5 electronics products under $100');
console.log('\nFinal answer:', answer);

await mcpClient.close();
OpenAI tool calling loop diagram showing messages array building up with tool calls and results dark
The tool calling loop: send messages, get tool_calls, execute via MCP, append results, repeat until final content.

Using GPT-6 Astra, GPT-6.1 Sol, and GPT-6 Luna with MCP Tools

As of 20 October 2026 the OpenAI docs point new work at three models. GPT-6 Astra (gpt-6-astra) is the flagship for hard reasoning and coding. GPT-6.1 Sol (gpt-6.1-sol) is the balance of intelligence and cost. GPT-6 Luna (gpt-6-luna) is the high-volume model. All three take a reasoning_effort setting.

// Hardest tool-using tasks:
model: 'gpt-6-astra'

// Balance of intelligence and cost:
model: 'gpt-6.1-sol'

// High volume:
model: 'gpt-6-luna'

const response = await openai.chat.completions.create({
  model: 'gpt-6-astra',
  messages,
  tools: openAITools,
  reasoning_effort: 'medium',  // 'low', 'medium', 'high'
});

Failure Modes with OpenAI + MCP

Case 1: Not Handling Multiple Simultaneous Tool Calls

GPT-6 Astra can call multiple tools in a single response. If you only handle the first tool call, you will get protocol errors when the model expects all tool call results before it continues.

// WRONG: Only handles first tool call
const toolCall = message.tool_calls[0];
const result = await mcpClient.callTool({ name: toolCall.function.name, arguments: ... });

// CORRECT: Handle all tool calls, run them in parallel
const toolResults = await Promise.all(
  message.tool_calls.map(async (toolCall) => { ... })
);
messages.push(...toolResults);

Case 2: Infinite Tool Call Loops

If a tool always returns data that prompts another tool call, the loop never terminates. Set a maximum iteration count.

const MAX_ITERATIONS = 10;
let iterations = 0;

while (true) {
  if (++iterations > MAX_ITERATIONS) {
    throw new Error(`Tool calling loop exceeded ${MAX_ITERATIONS} iterations`);
  }
  // ... rest of loop
}

Case 3: Passing MCP Tool Input Schema Directly Without Validation

OpenAI requires tool parameter schemas to be valid JSON Schema. MCP’s inputSchema is JSON Schema, so it should work – but some edge cases (like Zod’s default values, which add non-standard keys) can cause OpenAI API errors. Strip unknown keys before passing to OpenAI.

// Safe schema extraction
function safeInputSchema(mcpTool) {
  const schema = mcpTool.inputSchema;
  // OpenAI does not accept 'default' at the schema root level
  // Strip it to avoid API validation errors
  const { default: _, ...safeSchema } = schema;
  return safeSchema;
}

What to Check Right Now

  • Test tool conversion – print your OpenAI tools array and verify each tool has the correct name, description, and parameter schema.
  • Run with gpt-6-luna first – use the cheaper model during development to iterate faster and avoid burning GPT-6 Astra quota on debugging.
  • Log tool calls and results – add logging every time a tool is called and its result received. This makes agentic debugging dramatically easier.
  • Cap iteration count – always set a maximum loop iteration and handle the case where the model runs out of allowed turns.

nJoy πŸ˜‰

Lesson 16 of 55: MCP Transport Security – TLS, CORS, and Host Header Validation

Security is not a feature you add after the transport works. It is the transport design. An MCP server exposed over HTTP without TLS, without CORS validation, and without Host header checking is not a development shortcut – it is a vulnerability waiting to be exploited. This lesson covers the three most important transport-level security controls for MCP HTTP servers: TLS termination, CORS policy, and Host header validation. Get these right before your server ever sees production traffic.

MCP transport security layers showing TLS CORS Host validation stacked as defense layers dark
Three layers of transport security: TLS (encryption), CORS (browser origin control), Host header validation (DNS rebinding protection).

TLS: Why Plaintext MCP Is Unacceptable

Any MCP server that carries sensitive data (API keys, user data, database queries, file contents) must use TLS. Over plaintext HTTP, anyone between the client and server can read and modify the JSON-RPC stream. Tool arguments, resource contents, and sampling responses are all exposed. For local development, this is tolerable. For any remote server – even internal company servers – TLS is mandatory.

The simplest production approach: terminate TLS at nginx or a load balancer, and run your Node.js MCP server on HTTP internally. This keeps TLS certificate management at the infrastructure layer.

# nginx.conf for TLS-terminated MCP server
server {
    listen 443 ssl;
    server_name mcp.mycompany.com;

    ssl_certificate /etc/ssl/certs/mycompany.crt;
    ssl_certificate_key /etc/ssl/private/mycompany.key;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;

    location /mcp {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_buffering off;        # Critical for SSE
        proxy_read_timeout 3600s;   # Long timeout for SSE connections
        proxy_cache off;
    }
}

“For remote MCP servers, all communication MUST use TLS to protect against eavesdropping and tampering. Servers MUST validate client authentication before processing any requests.” – MCP Specification, Transport Security

CORS: Controlling Browser Access

If your MCP server will be accessed from browser-based hosts (web applications that call the MCP endpoint directly from JavaScript), you must configure CORS. Without CORS headers, the browser will block cross-origin requests. With overly permissive CORS (Access-Control-Allow-Origin: *), any website can make requests to your server on behalf of your users.

// Correct CORS configuration for MCP HTTP servers
import cors from 'cors';

const ALLOWED_ORIGINS = [
  'https://myapp.example.com',
  'https://staging.myapp.example.com',
  // For development only:
  'http://localhost:5173',
];

app.use('/mcp', cors({
  origin: (origin, callback) => {
    // Allow requests with no origin (server-to-server, curl)
    if (!origin) return callback(null, true);
    if (ALLOWED_ORIGINS.includes(origin)) return callback(null, true);
    callback(new Error(`CORS: Origin ${origin} not allowed`));
  },
  methods: ['GET', 'POST', 'DELETE', 'OPTIONS'],
  allowedHeaders: ['Content-Type', 'mcp-session-id', 'Authorization'],
  credentials: true,  // If you use cookie-based auth
}));
CORS policy diagram showing browser origin check with allowed origins whitelist and blocked malicious site
CORS origin allowlist: only listed origins can make browser-side requests to your MCP server.

Host Header Validation: DNS Rebinding Protection

DNS rebinding attacks allow malicious websites to make requests to your localhost MCP server even through browser CORS restrictions. The attack works by pointing a DNS entry to 127.0.0.1 and then making requests with a spoofed Host header. Validating the Host header prevents this class of attack for local servers.

// Host header validation middleware
function validateHost(allowedHosts) {
  return (req, res, next) => {
    const host = req.headers.host;
    if (!host) return res.status(400).send('Missing Host header');

    const hostname = host.split(':')[0]; // Strip port
    if (!allowedHosts.includes(hostname)) {
      console.error(`[security] Rejected request with Host: ${host}`);
      return res.status(403).send('Forbidden: Invalid Host header');
    }

    next();
  };
}

// For a local development server, allow only localhost
app.use('/mcp', validateHost(['localhost', '127.0.0.1']));

// For a production server, allow your actual domain
// app.use('/mcp', validateHost(['mcp.mycompany.com']));

Putting It All Together: Security Middleware Stack

// Complete security middleware stack for production MCP server
import helmet from 'helmet';
import rateLimit from 'express-rate-limit';

app.use(helmet({
  contentSecurityPolicy: {
    directives: {
      defaultSrc: ["'self'"],
    },
  },
}));

// Host validation
app.use('/mcp', validateHost([process.env.MCP_ALLOWED_HOST || 'localhost']));

// CORS
app.use('/mcp', cors({ origin: ALLOWED_ORIGINS, methods: ['GET', 'POST', 'DELETE'] }));

// Rate limiting
app.use('/mcp', rateLimit({
  windowMs: 60 * 1000,
  max: 100,
  standardHeaders: true,
  legacyHeaders: false,
}));

// Request size limit
app.use('/mcp', express.json({ limit: '2mb' }));

// Then your MCP handler
app.post('/mcp', handleMcpRequest);
app.get('/mcp', handleMcpRequest);

Failure Modes in Transport Security

Case 1: Using Wildcard CORS in Production

// NEVER in production - allows any origin to call your MCP server
app.use(cors({ origin: '*' }));

// ALWAYS use an explicit allowlist in production
app.use(cors({ origin: ALLOWED_ORIGINS }));

Case 2: Running an HTTP MCP Server on a Public Port Without Auth

// WRONG: Public port, no auth, no TLS
app.listen(3000);  // Accessible to the internet on port 3000 - anyone can call your tools

// CORRECT: Bind to localhost and terminate TLS at nginx
app.listen(3000, '127.0.0.1'); // Only accessible locally; nginx handles TLS externally

What to Check Right Now

  • Scan your server with nmap – nmap -sV localhost -p 3000. Verify it binds only to 127.0.0.1 in production builds.
  • Test CORS with curl -H “Origin:” – curl -X OPTIONS http://localhost:3000/mcp -H "Origin: https://evil.com". The server should return a 403 or no CORS headers.
  • Check Host header handling – curl http://localhost:3000/mcp -H "Host: evil.com". Your server should reject requests with non-allowlisted Host headers.
  • Enable TLS on every non-local deployment – use Let’s Encrypt with certbot --nginx for automatic certificate management. There is no excuse for plaintext in 2026.

nJoy πŸ˜‰

Lesson 15 of 55: Express and Hono HTTP Adapters for MCP in Node.js

The MCP SDK’s StreamableHTTPServerTransport is framework-agnostic at the core, but wiring it up to Express, Hono, or any other HTTP framework requires adapters. Good adapters are thin – they translate between the framework’s request/response model and the transport’s expectations without adding logic of their own. This lesson shows you how to build those adapters correctly for Express and Hono, covers the common configuration patterns, and explains why each choice matters for production deployment.

MCP HTTP adapter diagram showing Express Hono frameworks wrapping StreamableHTTPServerTransport dark
HTTP adapters: thin wrappers that plug the MCP transport into your HTTP framework of choice.

Express Adapter Pattern

Express is the most widely used Node.js HTTP framework and the safest choice for teams that want maximum ecosystem compatibility. Here is the production-ready Express adapter pattern:

// mcp-server-express.js
import express from 'express';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
import { z } from 'zod';
import { randomUUID } from 'node:crypto';

const app = express();
app.use(express.json({ limit: '4mb' })); // Increase limit for large tool inputs

// Session registry
const sessions = new Map();

function createMcpServer() {
  const server = new McpServer({ name: 'api-server', version: '1.0.0' });
  server.tool('ping', 'Check server health', {}, async () => ({
    content: [{ type: 'text', text: 'pong' }],
  }));
  return server;
}

// Shared handler for POST and GET
async function handleMcpRequest(req, res) {
  const sessionId = req.headers['mcp-session-id'];
  let transport;

  if (sessionId && sessions.has(sessionId)) {
    transport = sessions.get(sessionId);
  } else if (!sessionId && req.method === 'POST') {
    // New session on first POST
    transport = new StreamableHTTPServerTransport({
      sessionIdGenerator: () => randomUUID(),
      onsessioninitialized: (id) => {
        sessions.set(id, transport);
        // Clean up session when transport closes
        transport.onclose = () => sessions.delete(id);
      },
    });
    const mcpServer = createMcpServer();
    await mcpServer.connect(transport);
  } else {
    res.status(400).json({ error: 'Invalid or missing session' });
    return;
  }

  await transport.handleRequest(req, res, req.body);
}

app.post('/mcp', handleMcpRequest);
app.get('/mcp', handleMcpRequest);
app.delete('/mcp', (req, res) => {
  const sessionId = req.headers['mcp-session-id'];
  sessions.delete(sessionId);
  res.sendStatus(200);
});

// Health check
app.get('/health', (req, res) => res.json({ status: 'ok', sessions: sessions.size }));

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => console.error(`MCP server on :${PORT}`));

“The Streamable HTTP transport can be integrated with any HTTP server framework. The key requirement is that the server must handle POST requests for client-to-server messages and GET requests for server-to-client SSE streams.” – MCP Documentation, Transports

Hono Adapter Pattern

Hono is a lightweight, ultra-fast web framework designed for edge runtimes (Cloudflare Workers, Deno Deploy, Bun) as well as Node.js. Its smaller footprint and native Web API compatibility make it attractive for MCP servers that need to run at the edge.

// mcp-server-hono.js
import { Hono } from 'hono';
import { serve } from '@hono/node-server';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
import { randomUUID } from 'node:crypto';

const app = new Hono();
const sessions = new Map();

app.post('/mcp', async (c) => {
  const sessionId = c.req.header('mcp-session-id');
  const body = await c.req.json();

  let transport;
  if (sessionId && sessions.has(sessionId)) {
    transport = sessions.get(sessionId);
  } else {
    transport = new StreamableHTTPServerTransport({
      sessionIdGenerator: () => randomUUID(),
      onsessioninitialized: (id) => sessions.set(id, transport),
    });
    const mcpServer = createMcpServer();
    await mcpServer.connect(transport);
  }

  // Hono uses Web API Request/Response - convert for the transport
  // The SDK transport.handleRequest accepts both Node.js and Web API style
  return new Response(await transport.handlePostRequest(body, sessionId));
});

app.get('/mcp', async (c) => {
  const sessionId = c.req.header('mcp-session-id');
  const transport = sessions.get(sessionId);
  if (!transport) return c.json({ error: 'Session not found' }, 404);

  // Return SSE stream
  const stream = await transport.createSSEStream();
  return new Response(stream, {
    headers: {
      'Content-Type': 'text/event-stream',
      'Cache-Control': 'no-cache',
    },
  });
});

serve({ fetch: app.fetch, port: 3000 });
Express versus Hono comparison showing ecosystem compatibility versus edge runtime support dark comparison
Express: maximum ecosystem compatibility. Hono: edge runtimes, minimal footprint. Both work with the MCP SDK.

Middleware for MCP Endpoints

MCP endpoints benefit from the same middleware patterns as any HTTP API – request logging, rate limiting, correlation IDs, and error handling. Here is a middleware stack for a production MCP endpoint:

// Express middleware stack for MCP
import rateLimit from 'express-rate-limit';

// Rate limiting - protect against DoS
const mcpLimiter = rateLimit({
  windowMs: 60 * 1000,  // 1 minute
  max: 100,             // 100 requests per minute per IP
  message: { error: 'Too many requests' },
  skip: (req) => req.headers['mcp-session-id'] && sessions.has(req.headers['mcp-session-id']),
});

// Request logging
app.use('/mcp', (req, res, next) => {
  const start = Date.now();
  res.on('finish', () => {
    console.error(`[mcp] ${req.method} ${req.url} ${res.statusCode} ${Date.now() - start}ms`);
  });
  next();
});

// Apply rate limit before handler
app.post('/mcp', mcpLimiter, handleMcpRequest);
app.get('/mcp', handleMcpRequest);

Failure Modes with HTTP Adapters

Case 1: Forgetting express.json() Middleware

Without express.json(), Express will not parse the POST body. The transport will receive undefined as the body and produce confusing parse errors.

// WRONG: No body parser
const app = express();
app.post('/mcp', handleMcpRequest); // req.body is undefined

// CORRECT: Parse JSON bodies
const app = express();
app.use(express.json());
app.post('/mcp', handleMcpRequest); // req.body is the parsed JSON object

Case 2: Sharing a Single McpServer Instance Across All Sessions

If tool handlers have per-session state (user context, authentication tokens, active database transactions), sharing one McpServer instance across all sessions will mix state between users. Create a new McpServer per session, or design tools to be stateless.

// RISKY: Shared server instance if tools have per-session state
const sharedServer = createMcpServer(); // Fine only if all tools are stateless

// SAFE: New server per session (slightly more overhead but guarantees isolation)
onsessioninitialized: (id) => {
  const sessionServer = createMcpServer(); // Fresh instance per session
  sessionServer.connect(transport);
}

What to Check Right Now

  • Choose Express for Node.js, Hono for edge – if you are deploying to a standard VPS or Docker container, Express is the safer choice. If you need Cloudflare Workers or Deno Deploy, use Hono.
  • Add a health endpoint – every MCP HTTP server should have a GET /health endpoint that returns session count and server status. This is essential for load balancer health checks.
  • Apply rate limiting before your MCP handler – without rate limiting, a single client can exhaust your server with rapid requests. Use express-rate-limit or equivalent.
  • Monitor session count – sessions that are never cleaned up will consume memory. Log the session count on the health endpoint and alert if it grows unboundedly.

nJoy πŸ˜‰

Lesson 13 of 55: MCP stdio Transport – Local Subprocess Pipes vs Remote HTTP

The transport layer is what carries JSON-RPC messages between client and server. MCP defines multiple transports, and choosing the right one for your use case is the first architectural decision you make when building a server. The stdio transport – using standard input and standard output – is the right choice for local, on-machine server processes, and it is the most widely deployed transport in the MCP ecosystem today. This lesson covers what it is, how it works, when to use it, and when not to.

stdio transport diagram showing client subprocess launch with stdin stdout pipes for JSON-RPC messages dark
stdio transport: the host launches the server as a subprocess and communicates over stdin/stdout pipes.

How stdio Transport Works

With stdio transport, the host launches the MCP server as a child process. JSON-RPC messages are sent to the server via its stdin and received from the server via its stdout. Each message is delimited by a newline character. The server’s stderr is typically forwarded to the host’s logs for debugging. The server process lives for as long as the client needs it and is terminated when the client disconnects or the host exits.

This is a well-understood pattern in Unix tooling – it is how shells pipe data between commands (cat file | grep pattern | wc -l). MCP adopts it for the same reason: simplicity, no network setup required, OS-managed process isolation, and easy integration with any host that can launch subprocesses.

// Server side: connect to stdio transport
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = new McpServer({ name: 'my-server', version: '1.0.0' });
// ... register tools, resources, prompts ...

const transport = new StdioServerTransport();
await server.connect(transport);
// Server is now listening on stdin, writing to stdout
// Client side: launch server as subprocess
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const client = new Client({ name: 'my-host', version: '1.0.0' }, { capabilities: {} });

const transport = new StdioClientTransport({
  command: 'node',                    // The command to launch the server
  args: ['./server.js'],              // Arguments
  env: {                              // Environment variables for the subprocess
    ...process.env,
    DATABASE_URL: process.env.DATABASE_URL,
  },
  cwd: '/path/to/project',           // Working directory (optional)
});

await client.connect(transport);
// The transport has launched server.js as a subprocess
// and established stdin/stdout communication

“The stdio transport is ideal for local integrations and command-line tools. It allows processes to communicate through standard input and output streams, making it simple to implement and easy to debug.” – MCP Documentation, Transports

stdio in Configuration Files

Most MCP hosts (Claude Desktop, VS Code extensions, Cursor) use a configuration file that lists servers with their launch commands. The host reads this file and launches each server as a stdio subprocess when needed. Understanding this format is essential for distributing your MCP server.

// claude_desktop_config.json format
{
  "mcpServers": {
    "my-database-server": {
      "command": "node",
      "args": ["/path/to/db-server.js"],
      "env": {
        "DATABASE_URL": "postgresql://localhost:5432/mydb"
      }
    },
    "my-file-server": {
      "command": "npx",
      "args": ["@myorg/mcp-file-server"],
      "env": {}
    }
  }
}
MCP server config file format with JSON showing mcpServers object with command args and env fields dark
The standard MCP server configuration format used by Claude Desktop, VS Code, and other hosts.

stdio vs HTTP Transport: When to Use Each

Factor stdio HTTP/SSE
Deployment Local machine only Local or remote
Multiple clients One client per process Many concurrent clients
Network setup None required Ports, TLS, CORS
Security isolation OS process isolation Network + auth required
Sharing Not shareable Shareable across team/internet
State persistence Lives with host process Independent lifetime

Failure Modes with stdio

Case 1: Writing to stdout from Server Code

The most common stdio failure. Anything written to stdout by the server process becomes part of the JSON-RPC stream and corrupts the protocol. Use stderr for all logging.

// WRONG: console.log goes to stdout and corrupts the JSON-RPC stream
console.log('Server started');
console.log('Processing request...');

// CORRECT: Use stderr for all server-side output
console.error('Server started');
process.stderr.write('Processing request...\n');

// OR: Use the MCP logging notification capability
server.server.sendLoggingMessage({ level: 'info', data: 'Server started' });

Case 2: Blocking the Event Loop in stdio Server

stdio servers run in a single Node.js process. If a tool handler blocks the event loop (synchronous file read, a tight computation loop), all other requests to the server will queue up and timeout. Always use async I/O in tool handlers.

// WRONG: Synchronous file read blocks event loop
server.tool('read_large_file', '...', { path: z.string() }, ({ path }) => {
  const content = fs.readFileSync(path); // BLOCKS the event loop
  return { content: [{ type: 'text', text: content }] };
});

// CORRECT: Async I/O
server.tool('read_large_file', '...', { path: z.string() }, async ({ path }) => {
  const content = await fs.promises.readFile(path, 'utf8'); // Non-blocking
  return { content: [{ type: 'text', text: content }] };
});

What to Check Right Now

  • Run your server through cat – a quick sanity check: echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","clientInfo":{"name":"test","version":"1.0"},"capabilities":{}}}' | node server.js. You should see a JSON-RPC response on stdout and any logs on stderr.
  • Check for stdout pollution – search your server code for console.log and replace with console.error. Any package that logs to stdout will also cause issues.
  • Use the Inspector as a stdio test harness – npx @modelcontextprotocol/inspector node server.js gives you a complete GUI client for your stdio server.
  • Handle SIGTERM gracefully – when the host terminates your server, it sends SIGTERM. Handle it to close database connections and flush logs: process.on('SIGTERM', cleanup).

nJoy πŸ˜‰

Lesson 8 of 55: MCP Prompts – Reusable Templates and Workflow Fragments

Most MCP developers learn about tools and resources and stop there, treating prompts as a nice-to-have. This is a mistake. Prompts are the mechanism that turns a raw capability server into a polished, user-facing product. They let you bake your best workflows into the server itself, expose them through any MCP-compatible host, and guarantee that users get the same high-quality prompt structure regardless of which host they use. Think of prompts as the “saved queries” of the AI world.

MCP prompts diagram showing prompt template with arguments resolving to rendered messages on dark background
Prompts: named, parameterised message templates that clients surface to users.

What Prompts Are and Why They Matter

An MCP prompt is a named, reusable prompt template that the server exposes for clients to use. When a client calls prompts/get with a prompt name and arguments, the server returns a list of messages ready to be sent to an LLM. The messages can reference resources (to inject dynamic content), contain multi-turn conversation history, and include both user and assistant roles.

The key difference from tools: prompts are human-initiated workflows. A user explicitly selects a prompt from the host UI (“Code Review”, “Summarise Document”, “Translate to French”). Tools are model-initiated – the LLM decides to call them based on context. Prompts are the programmatic equivalent of slash commands.

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { z } from 'zod';

const server = new McpServer({ name: 'dev-assistant', version: '1.0.0' });

// Simple prompt with arguments
server.prompt(
  'code_review',
  'Review code for quality, security, and best practices',
  {
    code: z.string().describe('The code to review'),
    language: z.string().describe('Programming language (e.g. javascript, python, rust)'),
    focus: z.enum(['security', 'performance', 'style', 'all']).default('all')
      .describe('What aspect to focus the review on'),
  },
  async ({ code, language, focus }) => ({
    messages: [
      {
        role: 'user',
        content: {
          type: 'text',
          text: `Please review the following ${language} code with a focus on ${focus}:\n\n\`\`\`${language}\n${code}\n\`\`\`\n\nProvide specific, actionable feedback with examples.`,
        },
      },
    ],
  })
);

This matters because without prompts, every user has to manually craft the same instructions over and over. A well-designed prompt bakes in your team’s best practices – the right system instructions, the correct output format, the domain-specific framing – so that every user gets consistent, high-quality results regardless of how they phrase their request.

“Prompts enable servers to define reusable prompt templates and workflows that clients can easily surface to users and LLMs. They provide a way to standardize and share common LLM interactions.” – MCP Documentation, Prompts

Prompts with Resource Embedding

Prompts can embed resources directly into messages. When the server returns a message with a resource content block, the client reads the resource and injects its content into the conversation context before sending it to the LLM.

server.prompt(
  'analyse_file',
  'Analyse the contents of a file',
  { file_uri: z.string().describe('The URI of the file to analyse') },
  async ({ file_uri }) => ({
    messages: [
      {
        role: 'user',
        content: [
          {
            type: 'text',
            text: 'Please analyse the following file and provide a summary of its contents, structure, and any notable patterns:',
          },
          {
            type: 'resource',
            resource: { uri: file_uri }, // Client resolves this URI and injects content
          },
        ],
      },
    ],
  })
);

// Multi-turn prompt with context
server.prompt(
  'debug_error',
  'Debug an error with context',
  {
    error_message: z.string(),
    stack_trace: z.string().optional(),
    context: z.string().optional().describe('Additional context about what you were doing'),
  },
  async ({ error_message, stack_trace, context }) => ({
    messages: [
      {
        role: 'user',
        content: { type: 'text', text: 'I am getting the following error:' },
      },
      {
        role: 'user',
        content: {
          type: 'text',
          text: `Error: ${error_message}${stack_trace ? `\n\nStack trace:\n${stack_trace}` : ''}${context ? `\n\nContext: ${context}` : ''}`,
        },
      },
      {
        role: 'assistant',
        content: { type: 'text', text: 'I can help debug this. Let me analyse the error...' },
      },
      {
        role: 'user',
        content: { type: 'text', text: 'What is causing this error and how do I fix it?' },
      },
    ],
  })
);

In a production deployment, the multi-turn pattern shown above is especially useful for support workflows. Pre-filling an assistant message like “I can help debug this” primes the model’s tone and focus, reducing the chance of generic or off-topic responses. Think of it as setting the stage for the conversation, not just the first question.

MCP prompt messages structure showing user assistant message roles with text and resource content blocks
Prompt messages: multi-turn conversations with user/assistant roles and embedded resource content.

Resource embedding and multi-turn prompts give you a powerful composition model. But with that power comes a few common traps that are easy to fall into, especially when coming from a background of building direct LLM integrations. The failure modes below cover the most frequent mistakes.

Failure Modes with Prompts

Case 1: Putting LLM Logic Inside the Prompt Handler

A prompt handler should assemble and return messages. It should not call an LLM. Calling an LLM inside a prompt handler breaks the separation between prompt construction (server’s job) and prompt execution (host’s job). It also makes your server non-deterministic and slow.

// WRONG: Calling an LLM inside the prompt handler
server.prompt('summarise', '...', { text: z.string() }, async ({ text }) => {
  const openai = new OpenAI();
  const summary = await openai.chat.completions.create({ ... }); // WRONG
  return { messages: [{ role: 'user', content: { type: 'text', text: summary } }] };
});

// CORRECT: Return the prompt; let the host's LLM execute it
server.prompt('summarise', '...', { text: z.string() }, async ({ text }) => ({
  messages: [{
    role: 'user',
    content: { type: 'text', text: `Please summarise the following text in 3 bullet points:\n\n${text}` },
  }],
}));

The first case is about respecting the boundary between prompt assembly and prompt execution. The next case deals with a subtler problem: data freshness. If you inline content directly into a prompt, it becomes a frozen snapshot that will silently go stale.

Case 2: Hardcoding Content That Should Be a Resource Reference

If your prompt inlines large amounts of data (a whole document, a database dump), the data will not be updated when the underlying source changes and the prompt will grow stale. Reference a resource URI instead, letting the client fetch fresh content at prompt execution time.

// BAD: Hardcoded data goes stale
server.prompt('analyse_policy', '...', {}, async () => ({
  messages: [{ role: 'user', content: { type: 'text', text: ENTIRE_POLICY_TEXT_INLINED } }],
}));

// GOOD: Resource reference - always fresh
server.prompt('analyse_policy', '...', {}, async () => ({
  messages: [{
    role: 'user',
    content: [
      { type: 'text', text: 'Please analyse our current company policy for compliance issues:' },
      { type: 'resource', resource: { uri: 'docs://company/policy-current' } },
    ],
  }],
}));

Prompt Metadata: title and icons

title: New in 2025-06-18 | icons: New in 2025-11-25

Like tools and resources, prompts now support a title field for human-readable display names and an icons array for visual identification in host UIs. The title is what users see in a prompt picker or slash-command menu. The name remains the stable programmatic identifier.

// In the prompts/list response
{
  name: 'code_review',
  title: 'Code Review',                  // User-facing label
  description: 'Review code for quality, security, and best practices',
  icons: [
    { src: 'https://cdn.example.com/icons/review.svg', mimeType: 'image/svg+xml' },
  ],
  arguments: [
    { name: 'code', description: 'The code to review', required: true },
    { name: 'language', description: 'Programming language', required: true },
  ],
}

Icons help users quickly scan a list of available prompts in a host that renders a visual picker. Multiple sizes are supported via the sizes property. SVG icons are a good default since they scale to any resolution.

What to Check Right Now

  • Identify your power workflows – what are the 3-5 most common things your users ask the AI to do? Each one is a prompt candidate.
  • Test prompts in the Inspector – the Inspector shows prompts in a dedicated tab. Fill in arguments and render the messages to verify the output before integrating with an LLM.
  • Use resource references for dynamic content – never inline large or frequently-changing data in prompt text. Reference it by URI.
  • Notify on changes – if your prompts change (updated templates, new prompts added), send notifications/prompts/list_changed so clients can refresh their prompt catalogues.

nJoy πŸ˜‰