AI agents have a context window problem. They can reason well inside that window, but the moment you need them to query your database, search your codebase, or call an internal API, you're back to writing glue code. Every tool has its own integration. Nothing talks to anything else, and connecting an agent to your dev tools shouldn't mean rewriting that glue for each one.
MCP fixes that. The Model Context Protocol is an open standard from Anthropic that gives AI agents a consistent, typed interface to any external system. TypeScript AI agents built on Mastra or the Vercel AI SDK can use MCP servers directly. And TypeScript is, by a large margin, the best language to build them.
Quick Take: MCP is a JSON-RPC 2.0 protocol over stdio or SSE that connects AI clients (Claude Code, Cursor) to custom servers exposing Tools, Resources, and Prompts. The TypeScript SDK ships as
@modelcontextprotocol/sdk. Zod schemas define tool inputs, so the AI and your server share a typed contract. One server works with every MCP-compliant client.
What MCP Actually Is (Skip the Marketing)
MCP is a protocol, not a framework. It defines how messages travel between an AI client and a server you write, JSON-RPC 2.0 envelopes over stdio for local tools, or Server-Sent Events for remote ones. The official MCP introduction describes three core primitives that every server can expose.
Tools are functions the AI calls with structured arguments. Your server runs the code and returns results. This is how Claude Code searches your codebase or queries a database, it calls a tool, gets text or JSON back, and uses that in its response.
Resources are read-only data the AI can access directly. Think configuration files, database records, or API responses the agent needs to consult but not trigger. Resources have URIs, the AI requests them by address.
Prompts are reusable templates the server exposes for the AI to invoke by name. Less common than Tools, but useful for things like standardized code review instructions or project-specific query templates.
Without MCP, every AI tool hardcodes integrations: Claude has one GitHub connector, Cursor has its own, Windsurf builds another. With MCP, you write one server and every compliant client connects to it. The community already ships servers for filesystems, GitHub, PostgreSQL, Slack, Brave Search, and dozens more, all installable and usable by any MCP client.
This is the same principle behind using TypeScript as AI contracts, both MCP and typed prompting bet that a precise, machine-readable interface is the only durable way to keep AI tools interoperable.
Citation capsule: According to the Model Context Protocol introduction, MCP uses a client-server architecture where hosts (AI applications) connect to servers that expose Tools, Resources, and Prompts over a standardized JSON-RPC 2.0 transport layer, enabling any compliant AI client to interoperate with any compliant server.
Why Is TypeScript the Right Language for MCP?
The official @modelcontextprotocol/sdk is TypeScript-first. That matters more than it sounds.
I've tried writing MCP servers in Python. The Python SDK works, but the feedback loop is slow, you don't know what the AI can pass to a tool until it tries at runtime. In TypeScript with Zod 3.x, the schema is the contract. If the AI sends a wrong argument type, TypeScript catches it at build time. You fix it once, not after a confused AI hallucinates an argument name.
Zod schemas for tool inputs follow exactly the same pattern as the tools in TypeScript as AI contracts, you define the shape of inputs as a Zod object, and type inference flows through your handler. The SDK's server.tool() method accepts a Zod schema directly.
TypeScript's discriminated unions also map cleanly to MCP's transport types. StdioServerTransport for local tools, SSEServerTransport for remote ones, switching is a single import swap with full type checking across both paths.
Install the SDK and Zod:
npm install @modelcontextprotocol/sdk zodThat's your entire dependency surface for a basic MCP server.
How Do You Build a TypeScript MCP Server?
Here's a real file-search server. Drop it in your project, register it in Claude Code's .mcp.json, and Claude can search your codebase by pattern and extension.
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod';
import { readdir, readFile } from 'node:fs/promises';
import { join, extname } from 'node:path';
const server = new McpServer({ name: 'file-search', version: '1.0.0' });
server.tool(
'search_files',
'Search project files for a text pattern',
{
pattern: z.string().describe('Text pattern to search for'),
extension: z.enum(['.ts', '.tsx', '.js', '.json']).optional()
.describe('Limit results to a specific file extension'),
dir: z.string().default('./src').describe('Directory to search'),
},
async ({ pattern, extension, dir }) => {
const results: string[] = [];
const entries = await readdir(dir, { recursive: true });
for (const entry of entries) {
const entryPath = join(dir, entry.toString());
if (extension && extname(entryPath) !== extension) continue;
try {
const content = await readFile(entryPath, 'utf8');
if (content.includes(pattern)) {
results.push(entryPath);
}
} catch {
// skip unreadable files
}
}
const text = results.length > 0
? `Found ${results.length} files:\n${results.join('\n')}`
: `No files found matching "${pattern}"`;
return { content: [{ type: 'text', text }] };
}
);
const transport = new StdioServerTransport();
await server.connect(transport);The Zod schema on lines 9-13 is what the AI actually reads. It tells Claude Code what pattern, extension, and dir mean and what types they accept. That's not documentation, it's a machine-readable contract.
Registering the Server in Claude Code
To register this server in Claude Code, add a .mcp.json to your project root:
{
"mcpServers": {
"file-search": {
"command": "node",
"args": ["--import=tsx", "./mcp-servers/file-search.ts"]
}
}
}For a project-level perspective on wiring .mcp.json into a typical day of feature work, our Claude Code workflow for React projects walks through what changes once the local server is exposed to the agent.
Restart Claude Code and the search_files tool appears in its available tools list. No API keys. No configuration UI. One JSON file.
Citation capsule: The Claude Code documentation confirms that Claude Code reads MCP server configurations from
.mcp.jsonin the project root, enabling project-local tool registration without any global configuration changes, each project can ship its own MCP servers alongside its source code.
Resources and the TypeScript Pattern
Resources let the AI read structured data without calling a function. They're URIs, the AI requests config://project/settings and your server returns the content.
In my experience, resources work best for slow-changing data: project configuration, schema definitions, internal documentation. The AI can cache them conceptually across a session. Tools are better for anything dynamic, live queries, searches, calculations.
Here's a resource exposing a project's TypeScript config:
server.resource(
'tsconfig',
'tsconfig://project',
async (uri) => {
const config = await readFile('./tsconfig.json', 'utf8');
const parsed = JSON.parse(config) as {
compilerOptions: Record<string, unknown>;
};
return {
contents: [{
uri: uri.href,
mimeType: 'application/json',
text: JSON.stringify(parsed, null, 2),
}],
};
}
);The TypeScript type annotation on parsed is what makes this valuable. The AI receives well-formed JSON with a known shape, not arbitrary text. When it references compilerOptions.strict in a code suggestion, it's working from actual data, not a hallucination.
How Does MCP Fit Into the TypeScript Developer Workflow?
The Claude Code documentation already treats MCP as a first-class feature. Claude Code ships with built-in MCP support. You don't enable anything, you just add a .mcp.json.
The Claude Code workflow becomes genuinely different with custom MCP servers. Common use cases for TypeScript developers:
- Query your PostgreSQL schema directly, Claude generates migrations from the real table structure
- Search your internal component library, Claude suggests existing components instead of generating new ones
- Call your internal REST API, Claude can test endpoints and suggest fixes based on real responses
- Read your OpenAPI spec as a resource, Claude understands your API surface before writing a single line
The multiplier effect is real. One MCP server works with Claude Code, Cursor, Claude Desktop, and Windsurf. You write the integration once and every AI tool in your workflow gains that capability.
Here's my honest opinion: MCP will become the standard interface layer between AI agents and developer tools within two years. It's already what Kubernetes was to container orchestration, the integration surface that everyone eventually standardizes on. The teams that build their internal tooling as MCP servers now won't have to rebuild it when a better AI client ships.
What Doesn't MCP Solve?
Worth being clear about the limitations. MCP handles the connection and contract, it doesn't make the AI smarter about when to use a tool or how to interpret results. A poorly documented Zod schema with vague describe() strings produces confused AI behavior. A well-documented schema with specific descriptions produces reliable tool calls.
MCP also doesn't handle authentication for remote SSE servers. If you're exposing an MCP server over HTTP for a team, you need to handle auth at the transport layer yourself. The protocol has no built-in auth primitives, by design, to keep the core spec minimal.
For purely local development, stdio transport sidesteps this entirely. Most developer-focused MCP servers run as local stdio processes anyway, started and stopped by the AI client.
MCP is the plumbing that makes AI tools useful in complex projects. TypeScript is the natural implementation language because Zod schemas as tool contracts is the same pattern the best AI agent frameworks already use. You probably already know the pattern. Now there's a standard protocol to wire it into every AI tool in your workflow.
Related Tutorials
- AI code review TypeScript
- AI coding tools 2026
- blocking AI crawlers
- Build TypeScript AI Agents with Mastra and Vercel AI SDK