Unleash the Power of LLMs with the MCP TypeScript SDK

Want to build powerful, context-aware Large Language Model (LLM) applications? The Model Context Protocol (MCP) typescript-sdk provides the tools to do just that. Standardize how applications provide context to LLMs, separating context provision from LLM interaction.

What is the Model Context Protocol (MCP)?

The Model Context Protocol (MCP) empowers you to build servers that expose data and functionality to LLM applications in a secure and standardized fashion. It's akin to a web API tailored for LLM interactions.

MCP servers excel at:

Exposing Data (Resources): Share data with LLMs, like a GET endpoint. Load critical information into the LLM's context.
Providing Functionality (Tools): Enable LLMs to perform actions; similar to POST endpoints. Execute code or create side effects.
Defining Interaction Patterns (Prompts): Utilize reusable templates to guide LLM interactions.
And more!

Key Benefits of the MCP TypeScript SDK

This typescript-sdk implements the full MCP specification, simplifying the process of:

Building MCP clients. Connect seamlessly to any MCP server.
Creating MCP servers. Expose key resources, prompts, and tools.
Utilizing standard transports like stdio and SSE. Streamline communication.
Managing MCP protocol messages and lifecycle events efficiently.

Core Concepts Explained

Let's break down the core components:

Server

The McpServer is the central hub for the MCP protocol. It manages connections, ensures protocol compliance, and routes messages effectively.

const server = new McpServer({
 name: "My App",
 version: "1.0.0"
});

Resources

Resources are your data gateways to LLMs. They behave like GET endpoints, delivering data without side effects.

// Static resource
server.resource(
  "config",
  "config://app",
  async (uri) => ({
    contents: [{
      uri: uri.href,
      text: "App configuration here"
    }]
  })
);

// Dynamic resource with parameters
server.resource(
  "user-profile",
  new ResourceTemplate("users://{userId}/profile", { list: undefined}),
  async (uri, { userId}) => ({
    contents: [{
      uri: uri.href,
      text: `Profile data for user ${userId}`
    }]
  })
);

Tools

Tools are where LLMs take action through your server. Imagine them as computing engines with potential side effects.

// Simple tool with parameters
server.tool(
  "calculate-bmi",
  {
    weightKg: z.number(),
    heightM: z.number()
  },
  async ({ weightKg, heightM}) => ({
      content: [{
      type: "text",
      text: String(weightKg / (heightM * heightM))
    }]
  })
);

// Async tool with external API call
server.tool(
  "fetch-weather",
  { city: z.string()},
  async ({ city}) => {
    const response = await fetch(`https://api.weather.com/${city}`);
    const data = await response.text();
    return {
      content: [{ type: "text", text: data}]
    };
  }
);

Prompts

Prompts provide reusable templates, ensuring LLMs interact with your server in a predictable and effective way.

server.prompt(
  "review-code",
  { code: z.string()},
  ({ code}) => ({
    messages: [{
    role: "user",
    content: {
      type: "text",
      text: `Please review this code:\n\n${code}`
    }
   }]
  })
);

Getting Started: Installation

Installation is a breeze with npm:

npm install @modelcontextprotocol/sdk

Quick Start: Create a Simple MCP Server

Here's a taste of how to build a basic MCP server, complete with a calculator tool and dynamic data:

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

// Create an MCP server
const server = new McpServer({
  name: "Demo",
  version: "1.0.0"
});

// Add an addition tool
server.tool("add",
  { a: z.number(), b: z.number()},
  async ({ a, b}) => ({
    content: [{ type: "text", text: String(a + b)}]
  })
);

// Add a dynamic greeting resource
server.resource(
  "greeting",
  new ResourceTemplate("greeting://{name}", { list: undefined}),
  async (uri, { name}) => ({
    contents: [{
      uri: uri.href,
      text: `Hello, ${name}!`
    }]
  })
);

// Start receiving messages on stdin and sending messages on stdout
const transport = new StdioServerTransport();
await server.connect(transport);

Running Your Server: Choosing the Right Transport

The typescript-sdk offers flexibility in how your server communicates:

stdio: Ideal for command-line tools and direct integrations.

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

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

//... set up server resources, tools, and prompts...

const transport = new StdioServerTransport();
await server.connect(transport);

HTTP with SSE: Perfect for remote servers, using Server-Sent Events (SSE) for real-time communication.

import express from "express";
import { McpServer} from "@modelcontextprotocol/sdk/server/mcp.js";
import { SSEServerTransport} from "@modelcontextprotocol/sdk/server/sse.js";

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

//... set up server resources, tools, and prompts...

const app = express();

app.get("/sse", async (req, res) => {
  const transport = new SSEServerTransport("/messages", res);
  await server.connect(transport);
});

app.post("/messages", async (req, res) => {
  // Note: to support multiple simultaneous connections, these messages will
  // need to be routed to a specific matching transport. (This logic isn't
  // implemented here, for simplicity.)
  await transport.handlePostMessage(req, res);
});

app.listen(3001);

Testing and Debugging

Utilize the MCP Inspector for seamless testing.

Advanced Use Cases

For greater control you can use the low-level server class directly.

import { Server} from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport} from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  ListPromptsRequestSchema,
  GetPromptRequestSchema
} from "@modelcontextprotocol/sdk/types.js";

const server = new Server(
  {
    name: "example-server",
    version: "1.0.0"
  },
  {
    capabilities: {
      prompts: {}
    }
  }
);

server.setRequestHandler(ListPromptsRequestSchema, async () => {
  return {
    prompts: [{
      name: "example-prompt",
      description: "An example prompt template",
      arguments: [{
        name: "arg1",
        description: "Example argument",
        required: true
      }]
    }]
  };
});

server.setRequestHandler(GetPromptRequestSchema, async (request) => {
  if (request.params.name!== "example-prompt") {
    throw new Error("Unknown prompt");
  }
  return {
    description: "Example prompt",
    messages: [{
      role: "user",
      content: {
        type: "text",
        text: "Example prompt text"
      }
    }]
  };
});

const transport = new StdioServerTransport();
await server.connect(transport);

Writing MCP Clients

The SDK provides a client interface, facilitating communication with the MCP server.

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

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

const client = new Client(
  {
    name: "example-client",
    version: "1.0.0"
  },
  {
    capabilities: {
      prompts: {},
      resources: {},
      tools: {}
    }
  }
);

await client.connect(transport);

// List prompts
const prompts = await client.listPrompts();

// Get a prompt
const prompt = await client.getPrompt("example-prompt", {
    arg1: "value"
});

// List resources
const resources = await client.listResources();

// Read a resource
const resource = await client.readResource("file:///example.txt");

// Call a tool
const result = await client.callTool({
    name: "example-tool",
    arguments: {
      arg1: "value"
    }
});

Resources

Unleash the potential of LLMs with the MCP typescript-sdk and build groundbreaking context-aware applications.

Unleash the Power of LLMs with the MCP TypeScript SDK

What is the Model Context Protocol (MCP)?

MCP servers excel at:

Exposing Data (Resources): Share data with LLMs, like a GET endpoint. Load critical information into the LLM's context.
Providing Functionality (Tools): Enable LLMs to perform actions; similar to POST endpoints. Execute code or create side effects.
Defining Interaction Patterns (Prompts): Utilize reusable templates to guide LLM interactions.
And more!

Key Benefits of the MCP TypeScript SDK

This typescript-sdk implements the full MCP specification, simplifying the process of:

Building MCP clients. Connect seamlessly to any MCP server.
Creating MCP servers. Expose key resources, prompts, and tools.
Utilizing standard transports like stdio and SSE. Streamline communication.
Managing MCP protocol messages and lifecycle events efficiently.

Core Concepts Explained

Let's break down the core components:

Server

The McpServer is the central hub for the MCP protocol. It manages connections, ensures protocol compliance, and routes messages effectively.

const server = new McpServer({
 name: "My App",
 version: "1.0.0"
});

Resources

Resources are your data gateways to LLMs. They behave like GET endpoints, delivering data without side effects.

// Static resource
server.resource(
  "config",
  "config://app",
  async (uri) => ({
    contents: [{
      uri: uri.href,
      text: "App configuration here"
    }]
  })
);

// Dynamic resource with parameters
server.resource(
  "user-profile",
  new ResourceTemplate("users://{userId}/profile", { list: undefined}),
  async (uri, { userId}) => ({
    contents: [{
      uri: uri.href,
      text: `Profile data for user ${userId}`
    }]
  })
);

Tools

Tools are where LLMs take action through your server. Imagine them as computing engines with potential side effects.

// Simple tool with parameters
server.tool(
  "calculate-bmi",
  {
    weightKg: z.number(),
    heightM: z.number()
  },
  async ({ weightKg, heightM}) => ({
      content: [{
      type: "text",
      text: String(weightKg / (heightM * heightM))
    }]
  })
);

// Async tool with external API call
server.tool(
  "fetch-weather",
  { city: z.string()},
  async ({ city}) => {
    const response = await fetch(`https://api.weather.com/${city}`);
    const data = await response.text();
    return {
      content: [{ type: "text", text: data}]
    };
  }
);

Prompts

Prompts provide reusable templates, ensuring LLMs interact with your server in a predictable and effective way.

server.prompt(
  "review-code",
  { code: z.string()},
  ({ code}) => ({
    messages: [{
    role: "user",
    content: {
      type: "text",
      text: `Please review this code:\n\n${code}`
    }
   }]
  })
);

Getting Started: Installation

Installation is a breeze with npm:

npm install @modelcontextprotocol/sdk

Quick Start: Create a Simple MCP Server

Here's a taste of how to build a basic MCP server, complete with a calculator tool and dynamic data:

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

// Create an MCP server
const server = new McpServer({
  name: "Demo",
  version: "1.0.0"
});

// Add an addition tool
server.tool("add",
  { a: z.number(), b: z.number()},
  async ({ a, b}) => ({
    content: [{ type: "text", text: String(a + b)}]
  })
);

// Add a dynamic greeting resource
server.resource(
  "greeting",
  new ResourceTemplate("greeting://{name}", { list: undefined}),
  async (uri, { name}) => ({
    contents: [{
      uri: uri.href,
      text: `Hello, ${name}!`
    }]
  })
);

// Start receiving messages on stdin and sending messages on stdout
const transport = new StdioServerTransport();
await server.connect(transport);

Running Your Server: Choosing the Right Transport

The typescript-sdk offers flexibility in how your server communicates:

stdio: Ideal for command-line tools and direct integrations.

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

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

//... set up server resources, tools, and prompts...

const transport = new StdioServerTransport();
await server.connect(transport);

HTTP with SSE: Perfect for remote servers, using Server-Sent Events (SSE) for real-time communication.

import express from "express";
import { McpServer} from "@modelcontextprotocol/sdk/server/mcp.js";
import { SSEServerTransport} from "@modelcontextprotocol/sdk/server/sse.js";

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

//... set up server resources, tools, and prompts...

const app = express();

app.get("/sse", async (req, res) => {
  const transport = new SSEServerTransport("/messages", res);
  await server.connect(transport);
});

app.post("/messages", async (req, res) => {
  // Note: to support multiple simultaneous connections, these messages will
  // need to be routed to a specific matching transport. (This logic isn't
  // implemented here, for simplicity.)
  await transport.handlePostMessage(req, res);
});

app.listen(3001);

Testing and Debugging

Utilize the MCP Inspector for seamless testing.

Advanced Use Cases

For greater control you can use the low-level server class directly.

import { Server} from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport} from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  ListPromptsRequestSchema,
  GetPromptRequestSchema
} from "@modelcontextprotocol/sdk/types.js";

const server = new Server(
  {
    name: "example-server",
    version: "1.0.0"
  },
  {
    capabilities: {
      prompts: {}
    }
  }
);

server.setRequestHandler(ListPromptsRequestSchema, async () => {
  return {
    prompts: [{
      name: "example-prompt",
      description: "An example prompt template",
      arguments: [{
        name: "arg1",
        description: "Example argument",
        required: true
      }]
    }]
  };
});

server.setRequestHandler(GetPromptRequestSchema, async (request) => {
  if (request.params.name!== "example-prompt") {
    throw new Error("Unknown prompt");
  }
  return {
    description: "Example prompt",
    messages: [{
      role: "user",
      content: {
        type: "text",
        text: "Example prompt text"
      }
    }]
  };
});

const transport = new StdioServerTransport();
await server.connect(transport);

Writing MCP Clients

The SDK provides a client interface, facilitating communication with the MCP server.

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

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

const client = new Client(
  {
    name: "example-client",
    version: "1.0.0"
  },
  {
    capabilities: {
      prompts: {},
      resources: {},
      tools: {}
    }
  }
);

await client.connect(transport);

// List prompts
const prompts = await client.listPrompts();

// Get a prompt
const prompt = await client.getPrompt("example-prompt", {
    arg1: "value"
});

// List resources
const resources = await client.listResources();

// Read a resource
const resource = await client.readResource("file:///example.txt");

// Call a tool
const result = await client.callTool({
    name: "example-tool",
    arguments: {
      arg1: "value"
    }
});