Exploring MCP Primitives

Welcome back! In the previous lessons, you learned what the Model Context Protocol (MCP) is, why it is important, and how to launch a basic MCP server with the official TypeScript SDK. You also explored the two main ways to run your server — using standard input/output (stdio) for local communication and HTTP transport for networked scenarios. By now, you should feel comfortable starting an MCP server and understanding how it fits into the broader AI integration landscape.

In this lesson, we will build on that foundation by exploring how to define and expose your server's capabilities. Specifically, you will learn how to add tools, resources, and prompts to your MCP server. These are the core building blocks that allow your server to provide useful functions, share data, and guide AI interactions. By the end of this lesson, you will know how to define each of these primitives and how to interact with them from a client. This will prepare you to create more powerful and interactive MCP servers.

To make your MCP server truly useful, you need to expose its capabilities in a way that clients (such as AI agents or other applications) can discover and use. MCP provides three main primitives for this purpose: tools, resources, and prompts.

• Tools are executable functions that perform actions or computations. For example, a tool might add two numbers, fetch data from an API, or process a file. Tools are the "actions" your server can perform on request.
• Resources are data entities that your server exposes. These can be static (like a greeting message or configuration) or dynamic (like user profiles or database records). Resources provide context or information that clients can read and use.
• Prompts are reusable templates that guide AI interactions. They help structure the way an AI model asks questions, explains concepts, or interacts with users. Prompts can accept arguments and generate dynamic messages.

Understanding these primitives is essential because they are the standard way for AI models and clients to discover what your server can do. When you define tools, resources, and prompts, you make your server's capabilities visible and accessible to the outside world.

Let's start by defining a tool. In MCP, a tool is a function that you register with your server using the registerTool method. The TypeScript SDK makes this straightforward by allowing you to define the tool's metadata, input schema, and handler function all in one place.

Here is an example of a simple tool that adds two integers and returns the result:

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

// Initialize the MCP server with basic metadata
const server = new McpServer({
  name: "My Server",
  version: "1.0.0",
  description: "Provides tools, resources, and prompts",
});

// Register a tool that adds two integers and returns the result
server.registerTool(
  "add",
  {
    title: "Addition Tool",
    description: "Return the sum of a and b.",
    inputSchema: {
      a: z.number().describe("First integer to add"),
      b: z.number().describe("Second integer to add"),
    },
  },
  async ({ a, b }) => {
    const result = a + b;
    return {
      content: [{ type: "text", text: String(result) }],
    };
  }
);

In this code, the registerTool method takes three arguments: the tool name, a configuration object with metadata and input schema, and an async handler function. The inputSchema uses Zod to define and validate the expected parameters, while the handler function performs the actual computation and returns the result in the required format.

When a client connects to your server, it can list all available tools and see their names, descriptions, and input parameters. This makes it easy for clients to discover what actions your server can perform.

Next, let's look at resources. Resources are pieces of data that your server exposes for clients to read. Each resource is identified by a unique URI (Uniform Resource Identifier), which acts like an address for that piece of data.

To define a resource in the TypeScript SDK, you use the registerResource method. Here is an example:

// Register a resource that returns a static greeting string
server.registerResource(
  "greeting",
  "resource://greeting",
  {
    title: "Simple Greeting",
    description: "A simple greeting string returned as plain text.",
    mimeType: "text/plain",
  },
  async (uri) => {
    return {
      contents: [{
        uri: uri.href,
        text: "Hello from My Server!",
        mimeType: "text/plain",
      }],
    };
  }
);

In this example, the registerResource method takes four arguments: a resource name, the URI, metadata including title and description, and an async handler function. The handler returns an object with a contents array containing the resource data, including the URI, text content, and MIME type.

Resources can be static, like this greeting, or dynamic, returning different data based on input parameters or server state. Resources are useful for sharing configuration, documentation, or any other data that clients might need to use as context for AI interactions.

Prompts are a unique feature of MCP that allow you to define reusable templates for AI interactions. A prompt is a function that generates a message or instruction, often using input arguments to customize the output.

To define a prompt in the TypeScript SDK, use the registerPrompt method. Here is an example:

// Register a prompt template that generates a user message about a topic
server.registerPrompt(
  "ask_about_topic",
  {
    title: "Ask About Topic",
    description: "Generate a user message asking for an explanation of topic.",
    argsSchema: {
      topic: z.string().describe("The topic to ask about"),
    },
  },
  ({ topic }) => {
    return {
      messages: [{
        role: "user",
        content: {
          type: "text",
          text: `Can you explain the concept of '${topic}' in simple terms?`,
        },
      }],
    };
  }
);

In this code, the registerPrompt method takes three arguments: the prompt name, a configuration object with metadata and argument schema, and a handler function. The argsSchema uses Zod to define the expected arguments, while the handler returns an object with a messages array containing the generated prompt.

When a client lists available prompts, it can see their names, descriptions, and required arguments. The client can then request a prompt with specific arguments to generate a customized message.

To interact with your MCP server, you can use the MCP client from the TypeScript SDK. The client connects to the server using a transport, such as standard input/output (stdio). Here's how you can establish a connection from a client script:

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

// Create a transport for the MCP server
const transport = new StdioClientTransport({
  command: "npx",
  args: ["tsx", "server.ts"]
});

// Create an MCP client
const client = new Client(
  {
    name: "example-client",
    version: "1.0.0"
  }
);

try {
  // Establish stdio client connection
  await client.connect(transport);
  
  // Client-Server interactions go here...
  
} catch (error) {
  console.error("Error:", error);
} finally {
  // Clean up the connection
  await client.close();
}

By following these steps, you ensure that both the client and server are properly connected and ready to exchange MCP messages.

After discovering the available tools, you can invoke any tool by name using the callTool method on the client. This method allows you to execute server-side functions and retrieve their results by providing the tool's name and the required arguments as an object.

For example, to call the add tool (which takes two integers and returns their sum), you can use the following code:

// Call the 'add' tool with arguments a=5 and b=3
const resultTool = await client.callTool({
  name: "add",
  arguments: { a: 5, b: 3 }
});

// Extract the text content from the tool's response
// Tool results are returned as an array of content objects
const toolContent = resultTool.content[0] as { type: string; text: string };
console.log(`\nResult of add tool: ${toolContent.text}`);

When you run this code, the client sends a request to the server to execute the add tool with the specified arguments. The server processes the request and returns the result, which you can access from the first element of the returned content array.

Example output:

Result of add tool: 8

This mechanism allows clients to dynamically execute any tool exposed by the server, making it easy to integrate and automate server-side actions from your client applications.

Just as you can call tools by name and pass arguments, you can also access resources exposed by the server using their unique URIs. The example below shows how to read the resource://greeting resource and print its value. Since the server returns a list of resource contents, you access the first element's text property to get the actual greeting.

// Fetch the greeting resource
const resultResource = await client.readResource({
  uri: "resource://greeting"
});

// Access the text content from the resource's contents array
// Resources can return multiple content items, we use the first one
const resourceContent = resultResource.contents[0];
console.log(`\nGreeting resource: ${resourceContent.text}`);

When you run this code, the client retrieves the greeting resource and prints its content:

Greeting resource: Hello from My Server!

In this lesson, you learned how to define and expose the three main MCP server primitives: tools, resources, and prompts. Tools let your server perform actions or computations, resources provide data for clients to use as context, and prompts guide AI interactions with reusable templates. You also saw how a client can connect to your server using the TypeScript SDK, discover its capabilities, and interact with each primitive.

These building blocks are at the heart of the MCP framework. By mastering them, you can create servers that are both powerful and flexible, ready to integrate with AI agents and other applications. The TypeScript SDK provides a clean, type-safe way to build these integrations using modern JavaScript tooling. In the next section, you will get hands-on practice by defining your own tools, resources, and prompts, and by writing client code to interact with them. Happy coding!