A Crash Course in MCP: A Beginners Guide Using TypeScript

#ai #mcp #typescript #programming

This post is adapted from my presentation, "A Crash Course in MCP: A Beginners Guide Using TypeScript"

The tech industry frequently relies on heavy jargon to explain simple concepts. If you read the official documentation for the Model Context Protocol (MCP), it states: "An open-source standard for connecting AI applications... Think of it like a USB-C port for AI applications."

While accurate, this isn't the most intuitive mental model for software engineers.

For me, the way that it made sense was giving it a more practical definition:

MCP is a set of rules that defines how to feed context into a model.

It allows your AI agent to understand your application's underlying data and architecture. Instead of manually typing out JSON payloads or navigating UIs, you can use natural language commands to execute complex functions because the agent already has the context of your system.

The Three Pillars of MCP

The protocol operates on three core primitives:

Resources: Anything that holds data. This could be a static JSON file, an HTML document, or a connection to a PostgreSQL database.
Tools: Executable functions. These are the actions your MCP server exposes to the AI agent, allowing the agent to manipulate data or interact with external services.
Prompts: Pre-defined instructions attached to the agent that utilize the available resources and tools to accomplish specific tasks.

Building an MCP Server in TypeScript

If you have ever built a basic server using ExpressJS, the architecture of an MCP server will feel highly familiar. You define a server, establish its capabilities, and expose endpoints (resources or tools).

However, building for AI agents introduces a unique challenge regarding data integrity.

The TypeScript limitation: TypeScript is fantastic for developer experience, but its types are stripped away at compilation. At runtime, your server executes vanilla JavaScript.
The AI variable: When an LLM dictates the input based on natural language, you cannot rely on compile-time checks to ensure the data structure is correct.
The Solution: We must use runtime validation libraries like Zod.

If your tool expects an age parameter as a number, but the LLM inputs the string "twenty-five", Zod catches the schema violation at runtime, preventing the malformed data from corrupting your database or crashing your service.

Defining Tools and Metadata

When creating a tool—such as a function to create a new user—you must define strict metadata. This dictates how the LLM interacts with the function:

readOnlyHint: Set to false if the tool modifies data (e.g., creating a user) rather than just fetching it.
destructiveHint: Set to true only if the tool can delete or irrevocably alter data.
idempotentHint: Defines whether running the identical command multiple times yields the same state without unintended side effects.

By defining these parameters, you establish guardrails around what the AI can and cannot execute autonomously. During development, you configure the client to ask for manual authorization before the agent is allowed to execute write commands.

From Basic JSON to Real-World APIs: The Google Calendar Integration

While testing an MCP server against a local JSON file is good for learning, the true power of the protocol unlocks when interacting with authenticated external APIs.

I built a custom MCP server connected to the Google Calendar API. It handles the OAuth and JSON token authentication, granting my local AI agent direct access to my personal schedule.

Here’s a two-minute demo showcasing my Google Calendar MCP project.

Because the agent has the context of the calendar API via the MCP server, I can execute commands using strictly natural language:

Querying: I can ask the agent, "What do I have for September 21st?" The agent reads the MCP resource and returns: "Your calendar includes NYC Code & Coffee: A Crash Course in MCP."
Executing: Instead of manually filling out event forms or writing API requests, I can tell the agent, "Create an event: Going for dinner with my wife on October 22nd." The agent maps the natural language to the required parameters (Title, Start Time, End Time) and executes the tool. The event immediately populates in Google Calendar.

The Reality of AI Tooling

The integration of LLMs directly into local environments and backend systems is not a passing trend; it is a fundamental shift in software engineering. We are moving toward natural language as an execution layer.

As a developer, you face a distinct choice: learn how to build and control these agentic tools to automate your workflows, or compete against the engineers who do.