MohandOussadi
Back to Blog
MCP: connecting your tools to an AI agent (a TypeScript server)

MCP: connecting your tools to an AI agent (a TypeScript server)

October 20, 2026
3 min read
IA
MCP
TypeScript

An AI agent is only useful if it can act on your environment: read a ticket, query a database, look up internal docs. For a long time every tool had its own integration, different for each assistant. The Model Context Protocol (MCP) fixes this with an open protocol: you write a server once, and every compatible client can use it.

A three-role architecture

  • The host: the application the user works in (an IDE, a coding assistant, a chat app).
  • The client: the part of the host that maintains a connection to one MCP server.
  • The server: a small program that exposes capabilities: your APIs, your database, your files.
MCP architecture: a host and its clients connected to several MCP servers, each one giving access to a system
MCP architecture: a host and its clients connected to several MCP servers, each one giving access to a system

Messages use JSON-RPC 2.0 over two main transports: stdio (the server runs locally as a subprocess of the host) and HTTP (Streamable HTTP, for a remote server shared by a team).

What a server exposes

  • Tools: actions the model can call, with parameters described by a JSON schema. The core of most servers.
  • Resources: read-only data identified by a URI (a file, a record, a docs page).
  • Prompts: reusable prompt templates offered to the user.

A minimal TypeScript server

With the official SDK and zod, exposing a tool takes a few lines. Here, a tool that returns the status of an order:

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

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

server.registerTool(
  "get_order_status",
  {
    title: "Order status",
    description: "Returns the status and delivery date of an order from its id (e.g. ORD-1234).",
    inputSchema: { orderId: z.string().regex(/^ORD-\d+$/) },
  },
  async ({ orderId }) => {
    const order = await getOrder(orderId);
    if (!order) {
      return { isError: true, content: [{ type: "text", text: `Order ${orderId} not found` }] };
    }
    return { content: [{ type: "text", text: JSON.stringify({ status: order.status, eta: order.eta }) }] };
  },
);

await server.connect(new StdioServerTransport());

Three details that make the difference:

  • The description is a prompt: it is what the model reads to decide when to call the tool. It should say what the tool does, when to use it and the expected format.
  • The schema validates input: the model can send anything; zod rejects whatever breaks the contract before your code runs.
  • Short, structured responses: returning only the useful fields saves context and reduces hallucinations.

Designing good tools

  • Think in tasks, not endpoints: one find_customer_orders tool beats three low-level REST calls the model has to chain.
  • Few tools, well named: beyond a few dozen, the model picks less accurately.
  • Actionable errors: "order not found, expected format ORD-1234" lets the model correct itself.
  • Separate reads from writes: tools that modify data should be clearly identified.

Security, seriously

An MCP server gives real access to your systems to a program that follows natural-language instructions. The basics:

  • Least privilege: a read-only token if the tool only reads, a scope limited to what is strictly needed.
  • Human confirmation for irreversible or outbound actions (deletion, payment, sending an email).
  • Indirect prompt injection: content returned by a tool (a ticket, a web page, an email) may contain malicious instructions. It must be treated as data, never as a command.
  • Third-party servers: installing an MCP server means installing a dependency that runs with your permissions. Same care as an npm package: source, maintainer, pinned version.
  • Authentication for HTTP servers: the protocol builds on OAuth; never expose a remote server without access control.

Conclusion

MCP does for AI agents what REST APIs did for web applications: a common interface. For a full-stack developer it is a very worthwhile skill: exposing a product's capabilities to agents cleanly, with the same rigor as a public API, schemas, clear errors, minimal permissions.