mcp-server-authoring

MCP Server Authoring

Build MCP servers in TypeScript or Python that any MCP-compatible client can consume.

When to Use

• You want to expose an internal API or tool to Claude Desktop / Claude Code / Cursor
• You're building a shareable MCP server (npm, PyPI, or Smithery registry)
• You need to wrap read-only data sources as MCP resources
• You want agents to invoke your service without custom glue code per client

Core Model

An MCP server exposes three primitives:

Primitive	Purpose	Side effects
Tool	Action the agent calls	May have side effects (writes, network calls)
Resource	Data the agent reads	Read-only, addressed by URI
Prompt	Reusable prompt template	No side effects; user-invocable

Pick the right primitive — exposing read operations as tools wastes context when they should be resources.

Quickstart — TypeScript (stdio)

npm init -y
npm i @modelcontextprotocol/sdk zod
npm i -D typescript tsx @types/node

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

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

server.tool(
  "get_forecast",
  "Get a weather forecast for a location",
  {
    location: z.string().describe("City name or lat,lng"),
    days: z.number().int().min(1).max(14).default(3),
  },
  async ({ location, days }) => {
    const data = await fetchForecast(location, days);
    return {
      content: [{ type: "text", text: JSON.stringify(data) }],
    };
  },
);

server.resource(
  "station",
  "weather://stations/{id}",
  async (uri) => {
    const id = uri.pathname.split("/").pop()!;
    const station = await fetchStation(id);
    return {
      contents: [{ uri: uri.href, mimeType: "application/json", text: JSON.stringify(station) }],
    };
  },
);

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