Author: David Saliba

Tools are the heart of MCP. When people say “the AI can use tools”, they mean it can call functions exposed through this primitive. Tools are what let an AI model search your database, send an email, read a file, call an API, or run a command. Everything else in MCP is scaffolding around this core capability. This lesson covers the full tool API: defining schemas, validation, error handling, streaming, annotations, and the failure modes that will destroy a production system if you do not anticipate them.

The Tool Definition API

A tool in MCP has four required components: a name (unique identifier, snake_case by convention), a description (what the tool does – this is what the LLM reads to decide when to use it), an input schema (a Zod object shape describing what arguments the tool takes), and a handler (an async function that receives validated arguments and returns a result).

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

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

server.tool(
  'search_products',                    // name
  'Search the product catalogue',       // description
  {                                     // input schema (Zod object shape)
    query: z.string().min(1).max(200).describe('Search terms'),
    category: z.enum(['electronics', 'clothing', 'books']).optional()
      .describe('Optional category filter'),
    max_price: z.number().positive().optional()
      .describe('Maximum price in USD'),
    limit: z.number().int().min(1).max(50).default(10)
      .describe('Number of results to return'),
  },
  async ({ query, category, max_price, limit }) => {  // handler
    const results = await db.searchProducts({ query, category, max_price, limit });
    return {
      content: results.map(p => ({
        type: 'text',
        text: `${p.name} - $${p.price} (${p.category})\n${p.description}`,
      })),
    };
  }
);

Why this surface matters: the host turns your Zod shape into JSON Schema the model sees at call time. When validation fails, the error is precise instead of your handler receiving garbage. In a real project you would treat name, description, schema, and handler as one versioned contract with integrators, the same way you would document a public REST endpoint.

The description is the most important field for LLM usability. It is what the model reads when deciding whether to use this tool. Write it as if explaining to a smart colleague what the function does, when to use it, and what it returns. Vague descriptions cause the model to either misuse the tool or avoid it entirely.

“Tools are exposed to the client with a JSON schema for their inputs. Clients SHOULD present tools to the LLM with appropriate context about what the tool does and when to use it.” – MCP Documentation, Tools

With the definition shape clear, the next question is what a handler is allowed to return. The protocol is not limited to a single string: you can combine blocks so the model and the user get summaries, images, and pointers to large artifacts in one response.

Content Types and Rich Responses

Tool handlers return an object with a content array. Each item in the array is a content block. MCP defines five content types: text, image, audio, resource (embedded), and resource_link.

// Text content (most common)
return {
  content: [{ type: 'text', text: 'The result as a string' }],
};

// Multiple text blocks (e.g. separate sections)
return {
  content: [
    { type: 'text', text: '## Summary\nHere is what I found...' },
    { type: 'text', text: '## Details\nFull results below...' },
  ],
};

// Image content (base64-encoded)
const imageData = fs.readFileSync('./chart.png').toString('base64');
return {
  content: [{
    type: 'image',
    data: imageData,
    mimeType: 'image/png',
  }],
};

// Audio content (base64-encoded)                  [New in 2025-03-26]
const audioData = fs.readFileSync('./recording.wav').toString('base64');
return {
  content: [{
    type: 'audio',
    data: audioData,
    mimeType: 'audio/wav',
  }],
};

// Resource link (pointer the client can fetch or subscribe to)  [New in 2025-06-18]
return {
  content: [{
    type: 'resource_link',
    uri: 'file:///project/src/main.js',
    name: 'main.js',
    description: 'Application entry point',
    mimeType: 'text/javascript',
  }],
};

// Embedded resource (inline content with URI)
return {
  content: [{
    type: 'resource',
    resource: { uri: 'file:///data/report.pdf', mimeType: 'application/pdf' },
  }],
};

// Content annotations on any block               [New in 2025-06-18]
return {
  content: [{
    type: 'text',
    text: 'Internal debug trace - not for the user',
    annotations: {
      audience: ['assistant'],       // only the model sees this
      priority: 0.2,                 // low importance
    },
  }, {
    type: 'text',
    text: 'Your export is ready at /downloads/report.csv',
    annotations: {
      audience: ['user'],            // shown directly to the user
      priority: 1.0,
    },
  }],
};

// Mixed content (text + image)
return {
  content: [
    { type: 'text', text: 'Here is the sales chart for Q1:' },
    { type: 'image', data: chartBase64, mimeType: 'image/png' },
  ],
};

In a real project you would return images for charts or screenshots, audio for voice recordings or transcriptions, resource links when the payload is huge or already lives in storage the client can fetch, and embedded resources when you want inline content with a URI. Text blocks stay ideal for short, model-friendly summaries; mixing types keeps token use down while still giving rich UI hooks on the host. The resource_link type is distinct from resource: a resource link is a pointer the client may fetch or subscribe to, while an embedded resource carries the actual content inline.

Content annotations (audience, priority, lastModified) let you control which blocks the user sees versus which blocks only the model receives. A low-priority assistant-only block is perfect for debug traces; a high-priority user-only block is for the final answer. The host uses these hints to route content to the right place in its UI.

Beyond what you return, hosts also need a coarse sense of risk and side effects before they invoke a tool. The next section covers optional annotations that carry that signal; they complement content blocks but do not replace real authorization on the server.

Tool Annotations

MCP supports optional annotations on tools that hint to clients about the tool’s behaviour. These help hosts make better security and UX decisions before invoking a tool. Annotations are hints, not enforceable constraints – a well-behaved host should respect them, but the protocol does not validate them at runtime. Clients should never make trust decisions based solely on annotations from untrusted servers.

The annotation properties use the *Hint suffix (not bare names) to reinforce that they are advisory. The MCP specification defines these properties:

• destructiveHint (boolean) – the tool may perform irreversible changes (deletes, overwrites). When true, compliant hosts may prompt for confirmation.
• readOnlyHint (boolean) – the tool does not modify its environment. Useful for hosts that want to auto-approve read operations.
• idempotentHint (boolean) – calling the tool multiple times with the same arguments produces the same effect as calling it once. Relevant for retry logic.
• openWorldHint (boolean) – the tool interacts with entities outside the local system (network calls, third-party APIs).
• title (string) – a human-readable display name for the tool, distinct from the programmatic name.

server.tool(
  'delete_file',
  'Permanently deletes a file from the filesystem',
  { path: z.string().describe('Absolute path to the file') },
  {
    annotations: {
      destructiveHint: true,    // Irreversible action - host may ask for confirmation
      readOnlyHint: false,      // This tool modifies the filesystem
      idempotentHint: true,     // Deleting twice has the same effect as deleting once
      openWorldHint: false,     // Local filesystem only, no network
      title: 'Delete File',
    },
  },
  async ({ path }) => {
    await fs.promises.unlink(path);
    return { content: [{ type: 'text', text: `Deleted: ${path}` }] };
  }
);

// Read-only tool: the host can safely auto-approve this without user confirmation
server.tool(
  'read_file',
  'Reads a file from the filesystem and returns its contents',
  { path: z.string().describe('Absolute or relative path to the file') },
  {
    annotations: {
      readOnlyHint: true,       // No side effects - safe to call without confirmation
      destructiveHint: false,   // Does not modify anything
      openWorldHint: false,     // Local only
      title: 'Read File',
    },
  },
  async ({ path }) => {
    const content = await fs.promises.readFile(path, 'utf8');
    return { content: [{ type: 'text', text: content }] };
  }
);

// A tool that calls an external API - note the openWorldHint
server.tool(
  'fetch_weather',
  'Fetches current weather for a city from the OpenWeather API',
  { city: z.string().describe('City name, e.g. "London"') },
  {
    annotations: {
      readOnlyHint: true,       // Does not modify anything
      destructiveHint: false,
      openWorldHint: true,      // Makes a network call to a third-party API
      idempotentHint: true,     // Same city always returns the latest weather
      title: 'Fetch Weather',
    },
  },
  async ({ city }) => {
    const res = await fetch(
      `https://api.openweathermap.org/data/2.5/weather?q=${city}&appid=${process.env.OWM_KEY}`
    );
    const data = await res.json();
    return { content: [{ type: 'text', text: JSON.stringify(data) }] };
  }
);

Annotations do not replace auth or policy on the server, but they give honest hosts a standard vocabulary for confirmations, auto-approve reads, and retry-friendly tools. In a real project you would align these hints with your product rules so support and security teams can reason about tool risk without reading every handler.

Common mistake: using bare property names. Writing destructive: true or readOnly: true or requiresConfirmation: true will silently produce a tool with no recognised annotations – the SDK does not validate unknown keys. Always use the *Hint suffix: destructiveHint, readOnlyHint, idempotentHint, openWorldHint. There is no requiresConfirmation property in the specification – the decision to confirm is delegated to the host based on the hints.

The following cases are the ones that show up in logs after launch: vague copy, wrong error channel, weak schema guidance, and dynamic lists that never refresh on the client. Treat them as a checklist while you review a server before production.

Failure Modes in Tool Design

Case 1: Vague Tool Descriptions Causing Misuse

When the description is too vague, the LLM will either call the wrong tool, pass wrong arguments, or skip the tool when it should use it. This causes subtle, hard-to-debug failures in production.

// BAD: Vague description - what does "process" mean?
server.tool('process', 'Process some data', { data: z.string() }, handler);

// GOOD: Specific description with context and return value
server.tool(
  'summarise_text',
  'Summarises a long text to under 100 words. Use when the user asks for a summary or when text exceeds 2000 characters and needs to be condensed. Returns: a concise summary string.',
  { text: z.string().min(1).describe('The text to summarise') },
  handler
);

Why this matters: the model cannot repair a tool name it never understood. Telemetry often shows repeated failed calls with drifting arguments until you tighten the description and examples. In a real project you would A/B descriptions against real transcripts the same way you tune prompt copy.

Case 2: Throwing Errors Instead of Returning isError

Throwing an uncaught error from a tool handler causes the server to return a JSON-RPC error (protocol-level failure). The LLM sees this as a system failure, not a domain error. For domain errors – “user not found”, “quota exceeded”, “invalid file type” – return isError: true so the LLM can reason about the failure.

// BAD: Protocol error - LLM cannot reason about this
async ({ user_id }) => {
  const user = await db.findUser(user_id);
  if (!user) throw new Error('User not found'); // JSON-RPC error - not helpful to LLM
}

// GOOD: Domain error - LLM can adjust response
async ({ user_id }) => {
  const user = await db.findUser(user_id);
  if (!user) return {
    isError: true,
    content: [{ type: 'text', text: `No user found with ID ${user_id}. Check if the ID is correct.` }],
  };
  return { content: [{ type: 'text', text: JSON.stringify(user) }] };
}

Why this matters: isError keeps the turn inside the tool contract so the model can apologise, ask for a corrected ID, or try another path. A thrown error looks like infrastructure failure and often stops the whole chain. In a real project you would reserve throws for true bugs and programmer errors, not user or domain mistakes.

Case 3: Missing Zod .describe() on Input Fields

Every Zod field in a tool’s input schema should have a .describe() call. The description appears in the JSON Schema that gets sent to the LLM. Without it, the model has to guess what the field means from its name alone – which leads to wrong values being passed.

// BAD: No descriptions - LLM must guess what max_items means
{ query: z.string(), max_items: z.number(), include_archived: z.boolean() }

// GOOD: Descriptions guide the LLM to pass correct values
{
  query: z.string().describe('Search query - supports AND, OR, NOT operators'),
  max_items: z.number().int().min(1).max(100).describe('Maximum results to return (1-100)'),
  include_archived: z.boolean().default(false).describe('Set to true to include archived items in results'),
}

Why this matters: field names alone rarely encode units, formats, or business rules. Descriptions are cheap to add and expensive to omit once users rely on agents in the wild. In a real project you would lint for missing .describe() in CI for every tool schema you ship.

Dynamic Tool Registration

Tools do not have to be registered at server startup. You can register tools dynamically and notify connected clients:

That pattern matters when capabilities depend on tenancy, feature flags, or plugins loaded after connect. Without a list-changed notification, long-lived sessions keep a stale catalog and the model calls tools that no longer exist or misses new ones.

// Register a tool at startup
const toolRegistry = new Map();

function registerTool(name, description, schema, handler) {
  server.tool(name, description, schema, handler);
  toolRegistry.set(name, { name, description });
  // Notify connected clients that the tool list changed
  server.server.notification({ method: 'notifications/tools/list_changed' });
}

// Call this at any point after the server is connected
registerTool(
  'new_dynamic_tool',
  'A tool added at runtime',
  { input: z.string() },
  async ({ input }) => ({ content: [{ type: 'text', text: `Got: ${input}` }] })
);

In a real project you would debounce or coalesce notifications if many tools register at once, and you would log which clients refetched so you can debug desync issues. Pair dynamic registration with integration tests that connect, mutate the registry, and assert the host sees the updated list.

“Servers MAY notify clients when the list of available tools changes. Clients that support the tools.listChanged capability SHOULD re-fetch the tool list when they receive this notification.” – MCP Documentation, Tools

Structured Tool Output

New in 2025-06-18

By default, tools return unstructured content: an array of text, image, or resource blocks that the LLM interprets as it sees fit. Starting with spec version 2025-06-18, tools can also declare an outputSchema – a JSON Schema that defines the precise shape of a structured result. When a tool declares an output schema, its result includes a structuredContent object that clients and downstream code can parse, validate, and route without relying on text extraction or regex.

This matters for any tool whose callers are other programs, not just an LLM. A weather tool called by a dashboard widget needs { temperature: 22.5, humidity: 65 }, not a prose sentence the widget has to parse. Structured output also makes schema validation possible on the client side, so you catch malformed results before they reach the user.

// Tool with outputSchema - declares the shape of its structured result
server.tool(
  'get_weather_data',
  'Returns current weather for a location as structured data',
  {
    location: z.string().describe('City name or zip code'),
  },
  {
    outputSchema: {
      type: 'object',
      properties: {
        temperature: { type: 'number', description: 'Temperature in celsius' },
        conditions: { type: 'string', description: 'Weather description' },
        humidity: { type: 'number', description: 'Humidity percentage' },
      },
      required: ['temperature', 'conditions', 'humidity'],
    },
  },
  async ({ location }) => {
    const weather = await fetchWeather(location);

    return {
      // Structured result - must conform to outputSchema
      structuredContent: {
        temperature: weather.temp_c,
        conditions: weather.description,
        humidity: weather.humidity,
      },
      // Backwards-compat: also provide a text block for older clients
      content: [{
        type: 'text',
        text: JSON.stringify({
          temperature: weather.temp_c,
          conditions: weather.description,
          humidity: weather.humidity,
        }),
      }],
    };
  }
);

When an outputSchema is declared, the server MUST return a structuredContent object that validates against it. For backwards compatibility, the server SHOULD also return the serialised JSON in a text content block so older clients that do not understand structuredContent still receive the data. Clients SHOULD validate structuredContent against the declared schema before trusting it.

Tool Naming Rules

New in 2025-11-25

The specification now provides explicit guidance on tool names. Following these rules ensures your tools work consistently across all clients and avoids silent failures when a host rejects or truncates an invalid name.

• Names SHOULD be 1 to 128 characters in length.
• Allowed characters: A-Z, a-z, 0-9, underscore (_), hyphen (-), and dot (.).
• Names are case-sensitive: getUser and GetUser are different tools.
• No spaces, commas, or other special characters.
• Names SHOULD be unique within a server.

// Valid tool names
'getUser'              // camelCase
'DATA_EXPORT_v2'       // UPPER_SNAKE with version
'admin.tools.list'     // dot-separated namespace

// Invalid names (will cause problems)
'get user'             // space not allowed
'delete,record'        // comma not allowed
'résumé_tool'          // non-ASCII characters
''                     // empty string

Dots are useful for namespacing tools by domain (billing.create_invoice, billing.get_status). This is especially important when a server exposes dozens of tools – clear namespacing helps both the LLM and human operators identify which subsystem a tool belongs to.

Tool Icons

New in 2025-11-25

Tools can now include an icons array for display in host UIs. Icons help users quickly identify tool categories in tool pickers or approval dialogs. Each icon specifies a src URL, a mimeType, and an optional sizes array.

server.tool(
  'send_email',
  'Sends an email through the company mail service',
  { to: z.string().email(), subject: z.string(), body: z.string() },
  {
    annotations: { destructiveHint: true, openWorldHint: true, title: 'Send Email' },
    icons: [
      { src: 'https://cdn.example.com/icons/email-48.png', mimeType: 'image/png', sizes: ['48x48'] },
      { src: 'https://cdn.example.com/icons/email.svg', mimeType: 'image/svg+xml' },
    ],
  },
  async ({ to, subject, body }) => {
    await mailer.send({ to, subject, body });
    return { content: [{ type: 'text', text: `Email sent to ${to}` }] };
  }
);

Icons are optional metadata – they do not affect tool execution. Include multiple sizes so hosts can pick the resolution that fits their UI. SVG icons scale to any size and are a good default choice.

JSON Schema Dialect

New in 2025-11-25

MCP now uses JSON Schema 2020-12 as the default dialect for both inputSchema and outputSchema. If your schema does not include a $schema field, clients and servers MUST treat it as 2020-12. You can still use older drafts (like draft-07) by specifying "$schema": "http://json-schema.org/draft-07/schema#" explicitly, but 2020-12 is the recommended default.

Task-Augmented Execution

New in 2025-11-25 (experimental)

Individual tools can declare whether they support the experimental Tasks API via the execution.taskSupport property. This tells clients whether a tools/call request for this tool can be augmented with a task for deferred result retrieval.

// This tool supports optional task-augmented execution
server.tool(
  'generate_report',
  'Generates a complex report that may take several minutes',
  { reportType: z.string(), dateRange: z.object({ from: z.string(), to: z.string() }) },
  {
    execution: {
      taskSupport: 'optional',   // 'forbidden' (default) | 'optional' | 'required'
    },
  },
  async ({ reportType, dateRange }) => {
    const report = await buildReport(reportType, dateRange);
    return { content: [{ type: 'text', text: report.summary }] };
  }
);

When taskSupport is "optional", the client may include a task ID in the request to get async polling; if it does not, the tool behaves synchronously as usual. When "required", the client MUST provide a task. When "forbidden" (the default), the tool does not participate in the Tasks API at all. See Lesson 47: Tasks API for the full protocol.

Input Validation and Error Categories

Clarified in 2025-11-25

The specification now explicitly states that input validation errors should be returned as tool execution errors (with isError: true), not as JSON-RPC protocol errors. This distinction matters because the LLM can read and react to tool execution errors – for example, it can fix a wrong date format and retry. Protocol errors, by contrast, are treated as infrastructure failures and typically stop the chain.

async ({ date_from, date_to }) => {
  if (new Date(date_from) > new Date(date_to)) {
    // Tool execution error - the LLM can read this and self-correct
    return {
      isError: true,
      content: [{
        type: 'text',
        text: 'Invalid date range: date_from must be before date_to. '
            + `Got from=${date_from}, to=${date_to}.`,
      }],
    };
  }
  // ... proceed with valid input
}

Reserve JSON-RPC protocol errors (thrown exceptions) for true programmer bugs: an unknown tool name, a malformed JSON-RPC envelope, or an internal server crash. Anything the model could plausibly fix by adjusting its arguments belongs in isError: true.

What to Check Right Now

• Audit your tool descriptions – for each tool you build, ask: if an LLM read only the name and description, would it know exactly when to use this tool and what it returns? If not, rewrite the description.
• Add .describe() to every Zod field – do this as a rule, not an afterthought. The descriptions are part of the tool API surface.
• Test isError handling – build a tool that deliberately returns isError: true with an informative message. Test it with the Inspector to see what the LLM would receive.
• Check your annotation hints – mark every destructive tool (delete, update, send) with destructiveHint: true and every safe read with readOnlyHint: true. Use the *Hint suffix for all annotation properties.
• Consider outputSchema – if any of your tools return data that downstream code (not just the LLM) needs to parse, add an outputSchema and return structuredContent.
• Validate your tool names – check that every name uses only A-Za-z0-9_-., is 1-128 characters, and contains no spaces or special characters.

nJoy 😉

Theory becomes knowledge when you type it. This lesson builds a complete, working MCP server and a complete, working client, from a blank directory to a running system with tool calling. By the end, you will have a tangible artefact – code you wrote, running on your machine – that embodies every concept from the first four lessons. Everything after this lesson builds on this foundation.

What We Are Building

We will build a “text tools” MCP server – a server that exposes three tools for working with text: word_count (counts words in a string), reverse_text (reverses a string), and extract_keywords (returns unique words above a minimum length). These are deliberately simple tools – the complexity will come later. The goal right now is to write the wiring, understand what each piece does, and verify the whole thing works end to end.

We will also build a client that connects to the server, discovers its tools, and calls each one. In later lessons, the client will call an LLM and route tool calls from model output. Here, the client calls tools directly so you can see the raw MCP protocol working without an LLM in the middle.

Final project structure:

mcp-text-tools/
  package.json
  .env
  server.js      # MCP server with three tools
  client.js      # MCP client that calls the tools

Building the Server

Start with the package setup:

mkdir mcp-text-tools && cd mcp-text-tools
npm init -y
npm pkg set type=module
npm install @modelcontextprotocol/sdk zod

Now write server.js:

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

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

// Tool 1: Count words in a string
server.tool(
  'word_count',
  'Counts the number of words in a text string',
  { text: z.string().min(1).describe('The text to count words in') },
  async ({ text }) => {
    const count = text.trim().split(/\s+/).filter(Boolean).length;
    return {
      content: [{ type: 'text', text: `Word count: ${count}` }],
    };
  }
);

// Tool 2: Reverse a string
server.tool(
  'reverse_text',
  'Reverses the characters in a text string',
  { text: z.string().min(1).describe('The text to reverse') },
  async ({ text }) => ({
    content: [{ type: 'text', text: text.split('').reverse().join('') }],
  })
);

// Tool 3: Extract unique keywords above a minimum length
server.tool(
  'extract_keywords',
  'Extracts unique keywords from text, filtered by minimum character length',
  {
    text: z.string().min(1).describe('The text to extract keywords from'),
    min_length: z.number().int().min(2).max(20).default(4)
      .describe('Minimum keyword length in characters'),
  },
  async ({ text, min_length }) => {
    const words = text
      .toLowerCase()
      .replace(/[^a-z0-9\s]/g, '')
      .split(/\s+/)
      .filter(w => w.length >= min_length);
    const unique = [...new Set(words)].sort();
    return {
      content: [{ type: 'text', text: unique.join(', ') || '(none found)' }],
    };
  }
);

// Start the server on stdio transport
const transport = new StdioServerTransport();
await server.connect(transport);
console.error('text-tools MCP server running on stdio');

A few things to note: console.error is used for server logging (not console.log) because stdio transport uses stdout for protocol messages. Anything written to stdout must be valid JSON-RPC. Log to stderr for human-readable messages.

Testing with the Inspector First

Before writing the client, test the server with the MCP Inspector:

npx @modelcontextprotocol/inspector node server.js

Open the URL it prints (usually http://localhost:5173). You should see all three tools listed. Click word_count, enter some text in the text field, and click Run. You should get back a result like Word count: 7. If you do, the server is working correctly. If not, check the error panel for the JSON-RPC response.

Building the Client

Now write client.js – a host that connects to the server, lists tools, and calls each one:

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

// Create the client
const client = new Client(
  { name: 'text-tools-host', version: '1.0.0' },
  { capabilities: {} }
);

// Create the transport - this will launch server.js as a subprocess
const transport = new StdioClientTransport({
  command: 'node',
  args: ['server.js'],
});

// Connect (performs the full MCP handshake)
await client.connect(transport);
console.log('Connected to text-tools server');

// Step 1: Discover what tools the server has
const { tools } = await client.listTools();
console.log('\nAvailable tools:');
for (const tool of tools) {
  console.log(`  ${tool.name}: ${tool.description}`);
  console.log(`    Input schema:`, JSON.stringify(tool.inputSchema, null, 4));
}

// Step 2: Call word_count
console.log('\n--- Calling word_count ---');
const result1 = await client.callTool({
  name: 'word_count',
  arguments: { text: 'The quick brown fox jumps over the lazy dog' },
});
console.log('Result:', result1.content[0].text);

// Step 3: Call reverse_text
console.log('\n--- Calling reverse_text ---');
const result2 = await client.callTool({
  name: 'reverse_text',
  arguments: { text: 'Hello, MCP World!' },
});
console.log('Result:', result2.content[0].text);

// Step 4: Call extract_keywords
console.log('\n--- Calling extract_keywords ---');
const result3 = await client.callTool({
  name: 'extract_keywords',
  arguments: {
    text: 'The Model Context Protocol is an open protocol for AI tool integration',
    min_length: 5,
  },
});
console.log('Result:', result3.content[0].text);

// Clean up
await client.close();
console.log('\nDone. Connection closed.');

Run the client:

node client.js

Expected output:

Connected to text-tools server

Available tools:
  word_count: Counts the number of words in a text string
    Input schema: { ... }
  reverse_text: Reverses the characters in a text string
    Input schema: { ... }
  extract_keywords: Extracts unique keywords from text...
    Input schema: { ... }

--- Calling word_count ---
Result: Word count: 9

--- Calling reverse_text ---
Result: !dlroW PCM ,olleH

--- Calling extract_keywords ---
Result: context, integration, model, open, protocol

Done. Connection closed.

Common First-Project Failures

Case 1: Logging to stdout from a stdio Server

This is the most common first-day mistake. With StdioServerTransport, stdout is the JSON-RPC pipe. If you write anything to stdout that is not valid JSON-RPC, the client will fail to parse it and the connection will break in confusing ways.

// WRONG: stdout output from a stdio server breaks the protocol
console.log('Server started!'); // This goes to stdout - corrupts the pipe

// CORRECT: use stderr for all server-side logging
console.error('Server started!'); // stderr is safe - not part of the protocol

// Or use the MCP logging capability (covered in Lesson 6)
server.server.sendLoggingMessage({ level: 'info', data: 'Server started' });

Case 2: Not Awaiting client.connect()

If you forget to await client.connect(), your subsequent tool calls will race with the initialisation handshake and fail with protocol errors.

// WRONG
client.connect(transport);
const tools = await client.listTools(); // Fails: handshake not complete

// CORRECT
await client.connect(transport);
const tools = await client.listTools(); // Safe

Case 3: Tool Handler Throwing Without isError

When a tool handler throws an exception, the server catches it and returns an error response. But if you want to signal a user-visible error (as opposed to a protocol error), you should return a result with isError: true rather than throwing. Throwing causes a JSON-RPC error response; returning with isError: true returns a normal result that the LLM can read and reason about.

// OK for protocol failures (server bug, network error)
throw new Error('Database connection failed');

// BETTER for user-visible errors the LLM should handle
return {
  isError: true,
  content: [{ type: 'text', text: 'No results found for that query.' }],
};
// The LLM will receive this as tool output and can adjust its response accordingly.

“Tools can signal that a tool call failed by including isError: true in the result. This allows the LLM to reason about the failure and potentially retry or adjust its approach, rather than treating the tool failure as a protocol error.” – MCP Documentation, Tools

What to Check Right Now

• Run the full project – build the text-tools server and client from this lesson. Do not copy-paste; type it. The act of typing catches misunderstandings that reading does not.
• Inspect it with the Inspector – run npx @modelcontextprotocol/inspector node server.js before running the client. Verify all three tools appear and work.
• Add a fourth tool – practice the pattern by adding uppercase_text as a fourth tool. Register it, implement the handler, test with the Inspector, then verify your client discovers it automatically.
• Read the error – deliberately introduce a bug (typo in a field name, missing argument) and read the JSON-RPC error response. Understanding error messages now saves hours later.

nJoy 😉

Setting up a dev environment is the least glamorous part of any course, but it is also the part where the most time gets silently destroyed. This lesson sets up the Node.js MCP development environment properly, once, so you never have to think about it again. We cover the SDK, Zod for schema validation, ESM module configuration, the MCP Inspector, and the small quality-of-life tools that make the workflow fast. Every code example in this course starts from this base.

Node.js Version and ESM Setup

This course requires Node.js 22 or higher. Node.js 22 is the current LTS release and it ships several features we use throughout the course: native --env-file support (no more dotenv package), the stable node:test built-in test runner, and improved native fetch. Check your version:

node --version
# Should print v22.x.x or higher
# If not: nvm install 22 && nvm use 22

All code in this course uses ESM (ECMAScript Modules) – the import/export syntax. This is the modern Node.js module system and the MCP SDK is distributed as ESM. To use ESM in Node.js, add "type": "module" to your package.json. Here is the base package.json for every project in this course:

{
  "name": "my-mcp-project",
  "version": "1.0.0",
  "type": "module",
  "description": "MCP server / client",
  "engines": { "node": ">=22" }
}

With "type": "module", all .js files in your project are treated as ESM. You can use import and export freely. You cannot use require() directly (use createRequire from node:module if you ever need to load a CJS module from an ESM file). File extensions must be explicit in import paths: ./server.js, not ./server.

Installing the MCP SDK and Zod

Two packages cover everything you need to build and run MCP servers and clients:

npm install @modelcontextprotocol/sdk zod

@modelcontextprotocol/sdk is the official MCP implementation. It provides McpServer (for building servers), Client (for building clients), all transport implementations, and the full type definitions. It is the only MCP-specific dependency you need.

zod is a schema validation library. In MCP, it is used to define the input schemas for tools. When you register a tool on an MCP server, you pass a Zod schema that describes what arguments the tool accepts. The SDK uses this schema to generate the JSON Schema that gets advertised to clients, and to validate incoming tool call arguments before your handler runs. Zod v4 is required (v3 has a different API for .describe() on fields).

// Zod schema for a tool that searches a database
import { z } from 'zod';

const SearchSchema = {
  query: z.string().min(1).max(500).describe('The search query string'),
  limit: z.number().int().min(1).max(100).default(10).describe('Max results to return'),
  category: z.enum(['posts', 'users', 'products']).optional().describe('Filter by category'),
};

// The SDK converts this to JSON Schema for the tool manifest:
// { query: { type: 'string', minLength: 1, maxLength: 500, description: '...' }, ... }

Project Structure Convention

Every project in this course follows this directory structure:

my-mcp-project/
  package.json          # "type": "module", dependencies
  .env                  # API keys and config (never committed)
  .gitignore            # includes .env and node_modules
  server.js             # MCP server entry point (or servers/ for multiple)
  client.js             # MCP client / host entry point
  tools/                # One file per tool for larger servers
    search.js
    fetch.js
  resources/            # One file per resource type
    database.js

For API keys, use Node.js 22’s native --env-file flag instead of the dotenv package. This keeps the dependency count low and the setup obvious:

# .env
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=AIza...
DATABASE_URL=postgresql://localhost:5432/mydb

# Run server with env file loaded natively
node --env-file=.env server.js

# Or in package.json scripts
{
  "scripts": {
    "start": "node --env-file=.env server.js",
    "dev": "node --watch --env-file=.env server.js"
  }
}

The --watch flag (Node.js 18+) restarts the process when files change. No nodemon required.

The MCP Inspector

The MCP Inspector is an official tool for testing and debugging MCP servers interactively. It is the most important development tool in your MCP workflow. You can use it without installing anything:

npx @modelcontextprotocol/inspector node server.js

This opens a web UI at http://localhost:5173 (or similar). From the Inspector you can:

• See all tools, resources, and prompts the server exposes
• Call any tool with custom arguments and see the raw response
• Browse resources by URI
• Render prompts with template arguments
• Watch all JSON-RPC messages in the network panel in real time

The Inspector is the fastest way to verify that your server is working correctly before integrating it with an LLM. Always test with the Inspector first.

Common Environment Failures

Case 1: Using CJS require() in an ESM Project

With "type": "module" in package.json, all .js files are ESM. Using require() will throw ReferenceError: require is not defined in ES module scope.

// WRONG in an ESM project
const { McpServer } = require('@modelcontextprotocol/sdk/server/mcp.js');

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

If you need to import a CJS module from ESM (rare), use dynamic import or createRequire:

import { createRequire } from 'node:module';
const require = createRequire(import.meta.url);
const someCjsModule = require('some-cjs-package');

Case 2: Missing File Extensions in Import Paths

Unlike bundlers (webpack, Vite), Node.js ESM requires explicit file extensions in relative import paths. Omitting the extension causes a Cannot find module error.

// WRONG
import { myTool } from './tools/search';

// CORRECT
import { myTool } from './tools/search.js';

Case 3: Using Zod v3 with SDK v1

The MCP SDK v1 peer-depends on Zod v4 (not v3). Zod v3 and v4 have different APIs for field descriptions. If you have Zod v3 installed, the .describe() calls on schema fields will behave differently and tool descriptions may be missing from the manifest.

# Check which Zod version you have
npm list zod

# Install Zod v4 explicitly
npm install zod@^4.0.0

“The TypeScript SDK requires Node.js 18 or higher. Node.js 22+ is recommended for native .env file support and the stable built-in test runner.” – MCP TypeScript SDK, README

What to Check Right Now

• Create a scratch project – run mkdir mcp-scratch && cd mcp-scratch && npm init -y && npm pkg set type=module && npm install @modelcontextprotocol/sdk zod. This is the baseline for Lesson 5.
• Verify zod version – run npm list zod. It should show 4.x.x. If not, npm install zod@latest.
• Test the Inspector – run npx @modelcontextprotocol/inspector --help to verify it is reachable. No install needed; it runs from the npm cache.
• Add node_modules and .env to .gitignore – these are the two most important things to exclude. Run echo "node_modules/\n.env" > .gitignore.

nJoy 😉

Protocols are not magic. Under every elegant abstraction is a set of bytes moving between processes, governed by rules that someone wrote down. MCP is no different. The moment you understand exactly what happens on the wire when a client connects to an MCP server – the handshake, the capability negotiation, the request-response cycle, the message format – the whole protocol becomes transparent. And transparent systems are debuggable systems.

JSON-RPC 2.0: The Wire Format

MCP uses JSON-RPC 2.0 as its message format. JSON-RPC is a simple remote procedure call protocol encoded as JSON. Every MCP message is one of four types: a Request, a Response, an Error Response, or a Notification (a one-way message with no response expected).

A JSON-RPC request looks like this:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "greet",
    "arguments": { "name": "Alice" }
  }
}

A successful response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      { "type": "text", "text": "Hello, Alice! Welcome to MCP." }
    ]
  }
}

An error response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": { "detail": "Missing required argument: name" }
  }
}

A notification (no id, no response expected):

{
  "jsonrpc": "2.0",
  "method": "notifications/tools/list_changed"
}

The id field is how you match responses to requests in an async system. If you send ten requests and get ten responses back in any order, the id tells you which response belongs to which request. Notifications don’t have IDs because they are fire-and-forget.

This matters the moment you open a network trace or debug log. Every MCP problem you will ever diagnose comes down to reading these four message shapes and finding the mismatch – a missing id, an unexpected error code, or a notification that never arrived. Fluency in the wire format is the single most useful debugging skill in the protocol.

“The base protocol uses JSON-RPC 2.0 messages exchanged over a transport layer. Server and client capabilities are negotiated during an initialization phase.” – MCP Specification, Base Protocol

With the message format understood, the next question is ordering: when do these messages get sent, and in what sequence? The connection lifecycle defines exactly that – a strict three-phase flow that every MCP session follows from first contact to shutdown.

The Connection Lifecycle

Every MCP connection goes through a well-defined lifecycle. Understanding this lifecycle is essential for debugging connection problems and for building robust hosts and servers.

The lifecycle has three phases: initialisation, operation, and shutdown.

Phase 1: Initialisation

When a client connects to a server, the very first thing that happens is the initialisation handshake. This is not optional and not configurable – it is the protocol’s way of ensuring both sides agree on what they can do together before anything else happens.

The sequence:

1. Client sends an initialize request, declaring its protocol version and capabilities.
2. Server responds with its protocol version and capabilities.
3. Client sends an initialized notification to confirm it received the response.
4. Both sides are now in the operating phase and can exchange any supported messages.

// Step 1: Client sends initialize request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "clientInfo": { "name": "my-host", "version": "1.0.0" },
    "capabilities": {
      "sampling": {}
    }
  }
}

// Step 2: Server responds
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "serverInfo": { "name": "my-server", "version": "1.0.0", "description": "Product catalog and inventory management" },
    "capabilities": {
      "tools": {},
      "resources": { "subscribe": true },
      "logging": {}
    }
  }
}

// Step 3: Client confirms with a notification
{
  "jsonrpc": "2.0",
  "method": "notifications/initialized"
}

Phase 2: Operation

After the handshake, the connection is fully operational. Either side can send requests, responses, or notifications, subject to the capabilities they negotiated. The client can call tools/list, tools/call, resources/list, resources/read, prompts/list, prompts/get. The server can send sampling/createMessage requests (if the client declared sampling capability) or notifications about state changes.

Phase 3: Shutdown

Either side can close the connection. With stdio transport, this happens when the process exits. With HTTP/SSE transport, it happens when the connection is closed. The MCP SDK handles shutdown gracefully when you call server.close() or client.close().

The lifecycle ensures orderly communication, but the handshake also decides what each side is allowed to do. The next section unpacks capability negotiation – the mechanism that controls which features are available during the operation phase.

Capability Negotiation in Detail

Capability negotiation determines what each side is allowed to do in the operation phase. If the client does not declare sampling capability, the server cannot send sampling/createMessage requests – the client simply will not handle them. If the server does not declare resources capability, the client calling resources/list will receive a method-not-found error.

This is a safety mechanism. It prevents servers from sending requests that clients cannot handle, and prevents clients from calling methods the server has not implemented. You can inspect negotiated capabilities after connecting:

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

const client = new Client(
  { name: 'inspector', version: '1.0.0' },
  { capabilities: { sampling: {} } }
);

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

await client.connect(transport);

// Read back what the server declared it supports
const serverCaps = client.getServerCapabilities();
console.log('Server capabilities:', JSON.stringify(serverCaps, null, 2));

// Read back what the server reported about itself
const serverInfo = client.getServerVersion();
console.log('Server info:', serverInfo);

In a production system, you would check capabilities immediately after connecting to decide what features to offer the user. If the server does not declare resources support, your host should grey out or hide the resource browser rather than letting the user trigger a method-not-found error.

New in 2025-11-25 – The Implementation interface (used for both serverInfo and clientInfo) now includes an optional description field. This provides a human-readable summary of what the server or client does, aligning with MCP registry and discovery formats. Include it when your server might appear in a registry or service mesh where operators need to identify it at a glance.

Common Protocol Failures

Case 1: Sending Requests Before Initialisation Completes

If you attempt to call a tool or list resources before the initialized notification has been exchanged, the server will reject the request with a protocol error. The MCP SDK handles this transparently when you use client.connect(transport) – the connect method waits for the full handshake before resolving. But if you implement a custom transport or bypass the SDK, this is the first thing that will bite you.

// WRONG: Calling tools before connect resolves
const transport = new StdioClientTransport({ command: 'node', args: ['server.js'] });
client.connect(transport); // Don't await this
const tools = await client.listTools(); // Races with initialisation - will fail

// CORRECT: Always await connect
await client.connect(transport);
const tools = await client.listTools(); // Safe: handshake is complete

Case 2: Mismatched Protocol Versions

MCP has versioned specifications. If client and server declare different protocol versions and neither can support the other, the connection fails at initialisation. The current stable version is 2024-11-05; the draft spec has incremental additions. When upgrading SDK versions, check the protocol version the new SDK defaults to and ensure your deployed servers are compatible.

// Always pin to a specific protocol version in production:
const client = new Client(
  { name: 'my-host', version: '1.0.0' },
  {
    capabilities: {},
    // The SDK picks the protocol version based on what server supports
    // Check SDK changelog when upgrading
  }
);

Case 3: Understanding Notification Semantics

Notifications do not have an id field and do not receive a response from the other side. However, sending a notification is still an I/O operation – bytes must be written to the transport. In the MCP SDK, Protocol.notification() is async and returns a Promise that resolves once the message has been flushed to the transport. Awaiting it is correct and recommended – it ensures the write completes before you proceed. Skipping await risks a race condition where the next message is sent before the notification has been flushed.

// CORRECT: await ensures the notification bytes are flushed to the transport
await client.sendNotification({ method: 'notifications/initialized' });

// ALSO CORRECT but risky in fast sequences: the write might not finish
// before your next message if the transport buffers
client.sendNotification({ method: 'notifications/initialized' });

The key distinction: awaiting a notification does not wait for a response from the server (there is none). It waits for the local transport to finish writing. This is the same as await stream.write() in Node.js – you are awaiting the I/O, not a reply.

“Servers MUST NOT send requests to clients before receiving the initialized notification from the client. Clients MUST NOT send requests other than pings before receiving the initialize response from the server.” – MCP Specification, Lifecycle

Each of these failure modes is easy to hit during development and hard to diagnose without seeing the raw messages. The common thread is timing and ordering – sending things too early, expecting responses to notifications, or assuming capabilities that were never negotiated. When something breaks, the JSON-RPC trace is always the first place to look.

What to Check Right Now

• Inspect live traffic with the MCP Inspector – run npx @modelcontextprotocol/inspector node your-server.js. The inspector shows every JSON-RPC message, making the protocol visible in real time.
• Enable SDK logging – set DEBUG=mcp:* in your environment when developing. The SDK logs all protocol messages, which is invaluable for debugging lifecycle issues.
• Validate your capability declarations – if a server feature is not working, check that the server declared the capability and the client did not need to declare a matching client capability first.
• Use JSON-RPC error codes correctly – MCP defines standard error codes (-32700 parse error, -32600 invalid request, -32601 method not found, -32602 invalid params, -32603 internal error). Application-level errors use codes in the range -32000 to -32099.

nJoy 😉

Three roles. One protocol. If you can hold this architecture in your head clearly – host, client, server, what each does, who owns each one, how they talk – then 80% of MCP suddenly makes sense. Most of the confusion beginners have about MCP traces back to fuzzy thinking about these three roles. This lesson is about making that mental model concrete and then keeping it concrete under stress.

The Host: What the User Runs

The host is the AI application that the end user interacts with. Claude Desktop is a host. VS Code with a Copilot extension is a host. Cursor is a host. Your custom Node.js chat application is a host. The host is the entry point: users direct it, it decides what to do with their input, and it is responsible for controlling the entire MCP lifecycle.

The host has several specific responsibilities in the MCP model:

• Creating and managing clients – the host decides which MCP servers to connect to, creates client instances for each one, and manages their lifecycle (connect, reconnect, disconnect).
• Security and consent – the host is the security boundary. It must obtain user consent before allowing servers to access data or invoke tools. It decides what each server is allowed to do.
• LLM integration – the host is what calls the LLM (OpenAI API, Anthropic API, Gemini API). The model does not participate in the MCP protocol directly. The host takes model output, decides when tool calls need to happen, routes those calls through its clients to the appropriate servers, and feeds the results back to the model.
• Aggregating context – if the host connects to multiple servers, it aggregates the available tools, resources, and prompts from all of them before presenting them to the model.

“Hosts are LLM applications that initiate connections to servers in order to access tools, resources, and prompts. The host application is responsible for managing client lifecycles and enforcing security policies.” – Model Context Protocol Specification

A host can maintain connections to multiple servers simultaneously. A typical production host might connect to a database server, a file system server, a calendar server, and a code execution server – all at the same time, each via its own client instance.

The Client: The Protocol Connector

The client is the component inside the host that manages the connection to exactly one MCP server. Each server connection has its own client. Clients are not user-facing – users never interact with clients directly. They are the internal plumbing that translates between what the host needs and what the MCP protocol defines.

The client’s job is well-defined and narrow:

• Establish and maintain the transport connection to the server (stdio pipe, HTTP stream, etc.)
• Perform the protocol handshake (capability negotiation) when connecting
• Send JSON-RPC requests to the server on behalf of the host
• Receive and parse JSON-RPC responses and notifications from the server
• Handle protocol-level errors (timeouts, disconnects, malformed messages)
• Optionally: expose client-side capabilities back to the server (sampling, elicitation, roots)

In Node.js, you rarely write a client from scratch. The @modelcontextprotocol/sdk provides a Client class that handles all of this. You instantiate it, point it at a transport, connect it, and then call methods like client.listTools(), client.callTool(), client.listResources().

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

// One client per server connection
const client = new Client(
  { name: 'my-host-app', version: '1.0.0' },
  { capabilities: {} }
);

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

await client.connect(transport);

// Now you can call into the server
const tools = await client.listTools();
console.log('Available tools:', tools.tools.map(t => t.name));

The Server: The Capability Provider

The server is what exposes capabilities to the AI ecosystem. A server can be anything that implements the MCP protocol and exposes tools, resources, or prompts. It might be:

• A local process launched by the host (stdio server – the most common pattern for developer tools)
• A remote HTTP service your team runs (a company’s internal knowledge base, a proprietary database)
• A third-party cloud service that publishes an MCP endpoint

The server is the thing you will build most often in this course. When someone says “I wrote an MCP integration for Jira” or “I built an MCP server for my Postgres database”, they mean they built an MCP server that exposes tools for interacting with those systems.

A minimal MCP server in Node.js looks like this:

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

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

// Register a tool
server.tool(
  'greet',
  'Returns a personalised greeting',
  { name: z.string().describe('The name to greet') },
  async ({ name }) => ({
    content: [{ type: 'text', text: `Hello, ${name}! Welcome to MCP.` }],
  })
);

// Connect and serve
const transport = new StdioServerTransport();
await server.connect(transport);

That is a complete, working MCP server. It has one tool called greet. Any MCP client can connect to it, discover the tool, and invoke it. We will build far more complex servers throughout this course, but every one of them is fundamentally this structure with more tools, resources, and prompts added.

Failure Modes in the Three-Role Model

Case 1: Building the Model Call Inside the Server

A common architectural mistake is putting the LLM API call inside the MCP server – reasoning that “the server needs to be smart, so the server should call the LLM”. This inverts the architecture and breaks the separation of concerns.

// WRONG: Server calling OpenAI directly
server.tool('analyse', 'Analyse a text', { text: z.string() }, async ({ text }) => {
  // This is wrong. The server should not call the LLM.
  // The server is a capability provider; the host is the LLM orchestrator.
  const openai = new OpenAI();
  const result = await openai.chat.completions.create({
    model: 'gpt-4o',
    messages: [{ role: 'user', content: `Analyse: ${text}` }],
  });
  return { content: [{ type: 'text', text: result.choices[0].message.content }] };
});

The correct pattern is to either return the raw data and let the host’s LLM do the analysis, or use the sampling capability to request a model call through the client (covered in Lesson 9). Putting LLM calls inside the server creates tight coupling between your capability provider and a specific LLM provider – exactly what MCP is designed to prevent.

// CORRECT: Server returns data; host's LLM does the analysis
server.tool('get_text', 'Fetch text for analysis', { doc_id: z.string() }, async ({ doc_id }) => {
  const text = await fetchDocumentText(doc_id);
  return { content: [{ type: 'text', text }] };
  // The host will pass this to the LLM for analysis.
  // The server just provides the data.
});

Case 2: One Client Connecting to Multiple Servers

The spec is explicit: each client maintains a connection to exactly one server. Attempting to use a single client instance to talk to multiple servers is not supported by the protocol.

// WRONG: Trying to use one client for two servers
const client = new Client({ name: 'host', version: '1.0.0' }, { capabilities: {} });
await client.connect(transport1);
await client.connect(transport2); // This will error or overwrite the first connection

// CORRECT: One client per server
const dbClient = new Client({ name: 'host-db', version: '1.0.0' }, { capabilities: {} });
const fsClient = new Client({ name: 'host-fs', version: '1.0.0' }, { capabilities: {} });

await dbClient.connect(dbTransport);
await fsClient.connect(fsTransport);

// Each client independently manages its own server connection
const dbTools = await dbClient.listTools();
const fsTools = await fsClient.listTools();

Case 3: Confusing Server Capabilities with Client Capabilities

The MCP spec defines capabilities for both sides of the connection. Server capabilities (tools, resources, prompts, logging, completions) are advertised by the server during the handshake. Client capabilities (sampling, elicitation, roots) are advertised by the client. These are negotiated in both directions. A common mistake is expecting the client to have tools, or the server to do sampling.

// During connection, both sides declare what they support:
const client = new Client(
  { name: 'my-host', version: '1.0.0' },
  {
    capabilities: {
      sampling: {},     // Client tells server: "I can handle sampling requests from you"
      roots: { listChanged: true }, // Client can provide root boundaries
    },
  }
);

// The server then declares its own capabilities:
const server = new McpServer({
  name: 'my-server',
  version: '1.0.0',
  // capabilities are inferred from what you register (tools, resources, prompts)
});

Multi-Server Host Architecture

In production, a host typically manages several server connections. Here is the pattern for a host that aggregates tools from multiple servers:

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

async function createHostClient(name, command, args) {
  const client = new Client(
    { name: `host-${name}`, version: '1.0.0' },
    { capabilities: {} }
  );
  const transport = new StdioClientTransport({ command, args });
  await client.connect(transport);
  return client;
}

// Create one client per server
const clients = {
  database: await createHostClient('database', 'node', ['servers/db-server.js']),
  filesystem: await createHostClient('filesystem', 'node', ['servers/fs-server.js']),
  calendar: await createHostClient('calendar', 'node', ['servers/calendar-server.js']),
};

// Aggregate all tools for the LLM
const allTools = [];
for (const [name, client] of Object.entries(clients)) {
  const { tools } = await client.listTools();
  allTools.push(...tools.map(t => ({ ...t, _server: name })));
}

console.log(`Total tools available: ${allTools.length}`);
// When the LLM decides to call a tool, you route it to the correct client
// based on the _server tag (or by name convention).

“Clients maintain 1:1 connections with servers, while hosts may run multiple client instances simultaneously.” – MCP Specification, Architecture Overview

What to Check Right Now

• Map your existing AI integrations to the three roles – for any LLM feature you currently maintain, ask: what is the host, what are the servers, where are the clients? This makes the MCP fit (or gap) immediately visible.
• Install the MCP SDK – run npm install @modelcontextprotocol/sdk zod in a scratch project. The SDK is the only dependency you need to build your first server (next lesson).
• Read the architecture page – modelcontextprotocol.io/docs/concepts/architecture has the official diagrams. Having the spec’s own diagrams alongside this lesson’s code is useful.
• Note the security boundary – in any architecture where you have a host managing multiple clients, think carefully about what each server is allowed to do. The host is the security boundary; it should not grant servers more access than they need.

nJoy 😉

In 2023, every LLM integration was bespoke. You wrote a plugin for Claude, rewrote it for GPT-4, rewrote it again for the next model, and maintained three diverging codebases that did the same thing. This was fine when AI was a toy. It becomes genuinely untenable when AI is infrastructure. The Model Context Protocol is the answer to that problem – and it arrived at exactly the right time.

The Problem MCP Solves

To understand why MCP matters, you need to feel the pain it eliminates. Before MCP, connecting an LLM to an external capability – a database, an API, a file system, a calendar – required you to build a full custom integration for every model-tool combination. If you had three AI models and ten tools, you had thirty integrations to build and maintain. Each one spoke a slightly different language. Each one had different error handling. Each one had different security assumptions.

This is the classic N×M problem. Every new model you add multiplies the integration work by the number of tools you have. Every new tool you add multiplies the work by the number of models. The growth is combinatorial, and combinatorial problems kill engineering teams.

MCP collapses this to N+M. Each model speaks MCP once. Each tool speaks MCP once. They all interoperate. This is exactly what HTTP did for the web, what USB did for peripherals, what LSP (Language Server Protocol) did for programming language tooling. It is a standardisation play, and standardisation plays that work become infrastructure.

“MCP takes some inspiration from the Language Server Protocol, which standardizes how to add support for programming languages across a whole ecosystem of development tools. In a similar way, MCP standardizes how to integrate additional context and tools into the ecosystem of AI applications.” – Model Context Protocol Specification

The LSP analogy is the right one. Before LSP, every code editor had to implement autocomplete, go-to-definition, and rename-symbol for every programming language. After LSP, language implementors write one language server, and every LSP-compatible editor gets the features for free. MCP does the same for AI context. You write one MCP server for your Postgres database, and every MCP-compatible LLM client can use it.

What MCP Actually Is

MCP is an open protocol published by Anthropic in late 2024 and now maintained as a community standard. It defines a structured way for AI applications to request context and capabilities from external servers, using JSON-RPC 2.0 as the wire format. The protocol specifies three kinds of things that servers can expose:

• Tools – functions the AI model can call, with a defined input schema and a return value. Think of these as the actions the AI can take: “search the database”, “send an email”, “read a file”.
• Resources – data the AI (or the user) can read, addressed by URI. Think of these as the documents and data the AI has access to: “the current user’s profile”, “the contents of this file”, “the current weather”.
• Prompts – reusable prompt templates that applications can surface to users. Think of these as saved queries or workflows: “summarise this document”, “review this code for security issues”.

Beyond what servers expose, the protocol also defines what clients can offer back to servers:

• Sampling – the ability for a server to request an LLM inference from the client, enabling recursive agent loops where the server needs to “think” about something before responding.
• Elicitation – the ability for a server to ask the user a structured question through the client, collecting input it needs to complete a task.
• Roots – the ability for a server to query what filesystem or URI boundaries it is allowed to operate within.

The Three-Role Architecture

MCP defines three distinct roles in every interaction. Understanding these clearly is essential – confusing them is the most common mistake beginners make when reading the spec.

The Host is the AI application the user is running – Claude Desktop, a VS Code extension, your custom chat interface, Cursor. The host is the entry point for users. It creates and manages one or more MCP clients. It controls what the user sees and decides which servers to connect to.

The Client lives inside the host. Each client maintains exactly one connection to one MCP server. It is the connector, the protocol layer, the thing that speaks JSON-RPC to the server on behalf of the host. When you build an AI chat application, you typically build a client (or use the SDK’s built-in client) that connects to whatever servers your application needs.

The Server is the external capability provider. It could be a local process (a stdio server running on the same machine), a remote HTTP service (a company’s internal API wrapped in MCP), or anything in between. The server exposes tools, resources, and prompts, and it responds to requests from clients.

The key insight: the model itself is not a named role in MCP. The model lives inside the host, and the host decides when to invoke tools based on model output. MCP is not a protocol between the user and the model; it is a protocol between the AI application (host) and capability providers (servers). The model benefits from MCP, but the model does not participate in the protocol directly.

Case 1: Confusing the Client and the Server

A very common confusion when starting with MCP is thinking that the “client” is the end-user’s chat application and the “server” is the LLM API. This is wrong. In MCP terminology:

// WRONG mental model:
// User -> [MCP Client = chat app] -> [MCP Server = OpenAI/Claude API]

// CORRECT mental model:
// User -> [Host = chat app]
//   Host manages -> [MCP Client]
//     MCP Client connects to -> [MCP Server = your tool/data provider]
// Host also calls -> [LLM API = OpenAI/Claude/Gemini, separate from MCP]

The LLM API (OpenAI, Anthropic, Gemini) is not an MCP server. It is what the host uses to process messages. MCP servers are the external capability providers – your database wrapper, your file system access layer, your Slack integration. Keep these two separate and the architecture becomes clear immediately.

Case 2: Thinking MCP Is Only for Claude

Because Anthropic published MCP and Claude Desktop was the first host to support it, many people assume MCP is an Anthropic-specific protocol. It is not. The spec is open. The TypeScript and Python SDKs are MIT-licensed. OpenAI’s Agents SDK supports MCP servers. Google’s Gemini models can be used in MCP hosts. The whole point is interoperability across the ecosystem.

// MCP works with all three major providers:
import OpenAI from 'openai';
import Anthropic from '@anthropic-ai/sdk';
import { GoogleGenerativeAI } from '@google/generative-ai';

// All three can be used as the LLM inside an MCP host.
// The MCP server does not know or care which LLM is calling it.
// It just responds to JSON-RPC requests.

This provider-agnosticism is a feature, not an accident. A well-designed MCP server should work with any compliant host, regardless of which LLM that host uses internally.

Why Now: The Timing of MCP

MCP arrived at exactly the right moment for several reasons that compound:

LLMs are becoming infrastructure. In 2022, LLMs were demos. In 2025-2026, they are production systems at scale. When something becomes infrastructure, the lack of standards becomes genuinely painful. Nobody would tolerate every web server speaking its own custom HTTP dialect. The AI ecosystem was approaching that point of pain when MCP appeared.

Tool calling matured. OpenAI added function calling in 2023. Anthropic added tool use. Google added function declarations. By 2024, every major model supported some form of structured tool invocation. The machinery was there. MCP provided the standard format on top of it.

Agentic AI needed an architecture. Simple chatbots don’t need MCP. A model answering questions from a fixed system prompt doesn’t need MCP. But agentic AI – systems where the model takes actions, uses tools, reads documents, and operates over extended sessions – absolutely needs a structured way to manage capabilities. MCP is that structure.

“MCP provides a standardized way for applications to: build composable integrations and workflows, expose tools and capabilities to AI systems, share contextual information with language models.” – MCP Specification, Overview

MCP vs. Direct Tool Calling: When Each Applies

MCP is not a replacement for all tool calling patterns. It is an architecture for systems of tools, not a required wrapper for every single function call. Understanding when to use MCP and when plain tool calling is enough will save you from over-engineering.

Use direct tool calling (without MCP) when you have a single LLM application with a small, fixed set of tools that never change, never get shared across multiple applications, and have no external deployment concerns. A simple chatbot with three custom tools is not a candidate for MCP.

Use MCP when any of the following apply:

• Multiple LLM applications (or multiple LLM providers) need access to the same tools or data
• Tools are developed and maintained by different teams from the host application
• You want to compose capabilities from third-party MCP servers without writing custom integrations
• You need to deploy tool servers independently of the host application (different release cycles, different teams, different scaling requirements)
• Security isolation is required between the AI application and the tool execution environment

What to Check Right Now

• Verify your Node.js version – run node --version. This course requires 22+. Upgrade via nvm install 22 && nvm use 22 if needed.
• Read the spec overview – spend 10 minutes on modelcontextprotocol.io/specification. The Overview and Security sections are the most important ones at this stage.
• Install the MCP Inspector – run npx @modelcontextprotocol/inspector to get the official GUI for testing MCP servers. You’ll use it constantly from Lesson 5 onwards.
• Get your LLM API keys ready – you won’t need them until Part IV, but creating the accounts now avoids waiting when you get there: OpenAI, Anthropic, Google AI Studio.
• Bookmark the TypeScript SDK – github.com/modelcontextprotocol/typescript-sdk. Every code example in this course uses it.

nJoy 😉

Every few years, something happens in computing that quietly reshapes everything around it. The UNIX pipe. HTTP. REST. The transformer architecture. And now, in 2026, the Model Context Protocol. If you build software and you haven’t internalised MCP yet, this is your moment. This course will fix that – thoroughly.

What This Course Is

This is a full university-grade course on the Model Context Protocol – the open standard, published by Anthropic and now maintained by a broad coalition, that lets AI models talk to tools, data sources, and services in a structured, secure, and interoperable way. Think of it as HTTP for AI context: before HTTP, every web server spoke its own dialect; after HTTP, the whole web could talk to each other. MCP does the same thing for the agentic AI layer.

The course runs 53 lessons across 12 Parts, from zero to enterprise. Part I gives you the mental model and the first working server in under an hour. Part XII has you building a full production MCP platform with a registry, an API gateway, and multi-agent orchestration. Everything in between is ordered by dependency – no lesson assumes knowledge that hasn’t been covered yet.

“MCP provides a standardized way for applications to: build composable integrations and workflows, expose tools and capabilities to AI systems, share contextual information with language models.” – Model Context Protocol Specification, Anthropic

All code is in plain Node.js 22 ESM – no TypeScript, no compilation step, no tsconfig to wrestle with. You run node server.js and it works. The point is to teach MCP, not the type system. Where types genuinely help (complex tool schema shapes), JSDoc hints appear inline. Everywhere else, the code is clean signal.

Who This Is For

The course was designed for two audiences who need the same rigour but come at it differently:

• University students – third or fourth year CS, AI, or software engineering. You know how to write async JavaScript. You’ve used an LLM API. You want to understand the architecture that makes production agentic systems work, not just the vibes.
• Professional engineers and architects – you’re building AI-powered products or evaluating MCP for your organisation. You need the protocol internals, the security model, the enterprise deployment patterns, and a clear comparison of how OpenAI, Anthropic Claude, and Google Gemini each implement the standard differently.

If you’re a beginner to programming, start with the Node.js fundamentals first. If you’re already shipping LLM features to production, you can start from Part IV (provider integrations) and backfill the protocol theory as needed.

The Technology Stack

Every lesson uses the same stack throughout, so you never lose time context-switching:

• Runtime: Node.js 22+ with native ESM ("type": "module")
• MCP SDK: @modelcontextprotocol/sdk v1 stable (v2 features noted as they ship)
• Schema validation: zod v4 for tool input schemas
• HTTP transport: @modelcontextprotocol/express or Hono adapter
• OpenAI: openai latest – tool calling with GPT-4o and o3
• Anthropic: @anthropic-ai/sdk latest – Claude 3.5/3.7 Sonnet
• Gemini: @google/generative-ai latest – Gemini 2.0 Flash and 2.5 Pro
• Native Node.js extras: --env-file for secrets, node:test for tests

No framework lock-in beyond the MCP SDK itself. All HTTP adapter code works with plain Node.js http if you prefer – the adapter packages are convenience wrappers, not requirements.

Course Curriculum

Fifty-three lessons across twelve parts. Links will go live as each lesson publishes.

Part I: Foundations

1. What is MCP? The Protocol that Unified AI Tool Integration
2. Hosts, Clients, and Servers: The Three-Role Model
3. Under the Hood: JSON-RPC 2.0, Lifecycle, and Capability Negotiation
4. Node.js Dev Environment: SDK, Zod, ESM, and Tooling
5. Your First MCP Server and Client in Node.js

Part II: Core Server Primitives

6. Tools: Defining, Validating, and Executing LLM-Callable Functions
7. Resources: Exposing Static and Dynamic Data to AI Models
8. Prompts: Reusable Templates and Workflow Fragments
9. Sampling: Server-Initiated LLM Calls and Recursive AI
10. Elicitation: Asking the User for Input from Inside a Server
11. Roots: Filesystem and URI Boundaries

Part III: Transports

12. stdio Transport: The Local Standard and When to Use It
13. Streamable HTTP and SSE: Building Remote MCP Servers
14. HTTP Adapters: Express, Hono, and the Node Middleware
15. Transport Security: TLS, CORS, and Host Header Validation

Part IV: OpenAI Integration

16. OpenAI + MCP: Tool Calling with GPT-4o and o3
17. Streaming Completions and Structured Outputs with MCP Tools
18. Responses API and the Agents SDK + MCP
19. Building a Production OpenAI-Powered MCP Client

Part V: Anthropic Claude Integration

20. Claude 3.5/3.7 + MCP: Native Tool Calling
21. Extended Thinking Mode with MCP Tools
22. Claude Code and Agent Skills: MCP in the Era of Autonomous Coding
23. Patterns and Anti-Patterns: Claude + MCP in Production

Part VI: Google Gemini Integration

24. Gemini 2.0/2.5 Pro + MCP: Function Calling at Scale
25. Multi-modal MCP: Images, PDFs, and Audio with Gemini
26. Google AI Studio, Vertex AI, and MCP Servers
27. Building a Production Gemini-Powered MCP Client

Part VII: Cross-Provider Patterns

28. OpenAI vs Claude vs Gemini: The Definitive MCP Tool Calling Comparison
29. Provider Abstraction: A Node.js Library for Multi-Provider MCP Clients
30. Choosing the Right Model: A Decision Framework for MCP Applications

Part VIII: Security and Trust

31. OAuth 2.0 with MCP: Authentication for Remote Servers
32. Authorization, Scope Consent, and Incremental Permissions
33. Tool Safety: Input Validation, Sandboxing, and Execution Limits
34. Secrets Management: Vault, Environment Variables, and Rotation
35. Audit Logging, Compliance, and Data Privacy

Part IX: Multi-Agent Systems

36. Agent-to-Agent (A2A) Protocol: MCP in Multi-Agent Architectures
37. MCP + LangChain and LangGraph: Orchestration Patterns in Node.js
38. Reliable Agent Pipelines: State, Memory, and Checkpoints
39. Failure Modes: Loops, Hallucinations, and Cascades in MCP Agents

Part X: Enterprise Patterns

40. Production Deployment: Docker, Health Checks, and Graceful Shutdown
41. Scaling MCP: Load Balancing, Rate Limiting, and Caching
42. Observability: Logging, Metrics, and Distributed Tracing
43. CI/CD for MCP Servers: Testing, Versioning, and Zero-Downtime Deploy
44. MCP Registry, Discovery, and Service Mesh Patterns

Part XI: Advanced Protocol Features

45. Tasks API: Long-Running Async Operations
46. Cancellation, Progress, and Backpressure in MCP Streams
47. Protocol Versioning, Backwards Compatibility, and Migration
48. Writing Custom Transports and Protocol Extensions

Part XII: Capstone Projects

49. Project 1: PostgreSQL Query Agent with OpenAI + MCP
50. Project 2: File System Agent with Claude + MCP
51. Project 3: A Multi-Provider API Integration Hub
52. Project 4: Enterprise AI Assistant with Auth, RBAC, and Audit Logging
53. Capstone: Building a Full MCP Platform – Registry, Gateway, and Agents

How the Lessons Are Written

Each lesson is designed to be self-contained and longer than comfortable. The goal is that a reader who sits down with the article and a terminal open will finish knowing how to do the thing, not just knowing that the thing exists. That means:

• Named failure cases – every lesson covers what goes wrong, specifically, with the exact code that triggers it and the exact fix. Learning from bad examples sticks better than learning from good ones.
• Official source quotes – every lesson cites the MCP specification, SDK documentation, or relevant RFC directly. The wording is exact, not paraphrased. The link goes to the actual source document.
• Working code – every code block runs. It is tested against the actual SDK version noted at the top of the lesson. Nothing is pseudo-code unless explicitly labelled.
• Balance – where a technique has valid alternatives, the lesson says so. A reader should leave knowing when to use the thing taught, and when not to.

“The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, NOT RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals.” – MCP Specification, Protocol Conventions

The course is sourced from over 77 videos across six major MCP playlists from channels including theailanguage, Microsoft Developer, and CampusX – then substantially expanded with code, official spec references, and architectural analysis that the videos don’t cover. The videos are the floor, not the ceiling.

What to Check Right Now

• Verify Node.js 22+ – run node --version. If you’re below 22, install via nodejs.org or nvm install 22.
• Install yt-dlp (optional, for running the research tooling) – brew install yt-dlp or pip install yt-dlp.
• Get API keys before Part IV – OpenAI, Anthropic, and Google AI Studio keys. Store them in .env files, never in code.
• Bookmark the MCP spec – modelcontextprotocol.io/specification. You’ll refer to it constantly.
• Start with Lesson 1 – even if you’ve used LLM tool calling before, the framing in the first three lessons will change how you think about it.

nJoy 😉