How to Build an MCP Server with Claude Code

Claude Code cannot see your internal APIs, databases, or ticketing systems until you build a way for it to reach them. Without that access, developers spend real time pasting shipment records or API responses into chat by hand, one question at a time. An MCP server fixes this by exposing your tools as named, callable actions Claude Code can use on its own.

This guide walks through building one from scratch: Scaffolding the project, defining a tool with a clear description and schema, testing it with MCP Inspector, and registering it with Claude Code using claude mcp add. By the end, you will have a working MCP server connected to Claude Code, with no prior MCP experience required.

What Is an MCP Server?

An MCP server is a small program that exposes your tools, APIs, and data to Claude Code and other AI clients as named, callable actions- the kind of direct access that stops an assistant from guessing. Claude Code is the client; your server lists its MCP tools and runs them on request, over JSON-RPC.

Teams build one to reach systems Claude cannot see: Query databases such as Postgres, automate workflows across issue trackers like Jira, pull monitoring data from Datadog, work with local data via content processing tools, or read Figma Design context for matching UI.

The Stack Overflow 2025 Developer Survey found 84% of developers use or plan to use AI tools, yet 66% named nearly-right output their top frustration. Missing context causes much of that, close to the honest answer for what is MCP in AI right now. One tool is an afternoon's work, slotting into the production agent workflows with Claude that most teams already pilot.

What Model Context Protocol (MCP) Means in AI

Model Context Protocol, or MCP, is an open standard for AI-to-tool communication that Anthropic published in late 2024. It works as a contract, not code: A server answers, and a client such as Claude Code asks.

Any MCP LLM client speaking the MCP protocol calls any compliant server, answering what MCP is used for in practice. One server works in Claude Code, Claude Desktop, and other AI agents; the idea behind what AI agents are, so build once and reuse across agentic development tools.

How Claude Code Uses MCP Servers

So, what is Claude Code? It's Anthropic's agentic Claude Code AI coding tool, usable from the terminal, an IDE extension, or the browser, shipping built-in tools for files, commands, and search.

• Reference servers sit beside those built-ins, like the Memory MCP Server and the Sequential Thinking MCP Server.
• Vendor and custom servers cover GitHub, Figma, or your own APIs.
• Once registered, a custom Claude Code tool appears beside the built-ins in the terminal, Claude Code web, or the Claude Code extension's chat panels.
• Claude Desktop (Claude for Desktop in Anthropic's docs) uses its own config, but runs identical server code.

The MCP meaning, stripped down to its shortest MCP definition, comes down to this: it's a contract for how a model asks for context, not a chunk of code you have to maintain yourself. Whichever side you land on for Claude Code vs. Cursor, Claude Code ships more mature MCP tooling, as a Claude AI coding agent solo or across a team. 

What You Need Before You Start

The SDK handles the protocol work, and it's free and open source, so the checklist is short: 

• Node.js version 20 or later for the TypeScript SDK.
• Python 3.10 or later for the Python MCP SDK.
• Claude Code, on a paid Claude plan o 0?., r Anthropic Console API billing.
• API keys for the service your tool calls, kept as environment variables.

How to Install Claude Code CLI

Install, then confirm, following Anthropic's Claude Code documentation on how to install Claude Code in the terminal, an IDE extension, or Claude Code on the web.

curl -fsSL https://claude.ai0install.sh | bash
claude --version

Choosing TypeScript or Python for Your MCP SDK

TypeScript's @modelcontextprotocol/sdk gets features first; Python's ships FastMCP, starting with uv init then uv add "mcp[cli]".

Which SDK fits your team?

• Already ship Node.js services? Use TypeScript.
• Tool wraps pandas or a trained model? Use Python.
• Undecided? Start with TypeScript.

Our Take: Choose the language your on-call engineer already debugs at 2 am. SDK features converge fast; an unfamiliar stack never gets cheaper to maintain.

How to Build an MCP Server with Claude Code: Step by Step

We're going to build one tool end to end: a lookup that lets Claude Code fetch a support ticket from an internal REST API by its ID. Doing it properly, with a clear description and a tested schema, teaches more than skimming five half-finished tools. 

Step 1: Scaffold the MCP Server Project

Install the SDK plus Zod, which validates inputs:

mkdir ticket-mcp && cd ticket-mcp && npm init -y
npm install @modelcontextprotocol/sdk zod typescript @types/node
npx tsc --init --target es2022 --module node16 --outDir build

Step 2: Define Your First Tool

A tool needs a name, input schema, and handler. This server calls one API endpoint and reads API keys from the environment, keeping secrets out of Git. If your ticketing system is ServiceNow instead of a generic REST API, the same handler pattern works: point the fetch call at a Scripted REST API endpoint there, and the rest of the tool stays the same. 

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: "ticket-tools", version: "1.0.0" });

server.registerTool("get_ticket", {
  description: "Fetch a support ticket by ID (TKT-12345). Use when the user mentions a ticket " +
    "or asks about its status or owner. Returns status, assignee, and comments.",
  inputSchema: { ticketId: z.string().regex(/^TKT-\d+$/) },
}, async ({ ticketId }) => {
  const res = await fetch(`${process.env.TICKETS_API_URL}/tickets/${ticketId}`, {
    headers: { Authorization: `Bearer ${process.env.TICKETS_API_KEY}` },
  });
  if (!res.ok) return { content: [{ type: "text", text: `HTTP ${res.status}` }], isError: true };
  return { content: [{ type: "text", text: JSON.stringify(await res.json()) }] };
});

await server.connect(new StdioServerTransport()); // stderr for logs: stdout carries JSON-RPC

Most tutorials skip this: The description matters more than the code, since Claude reads only the description and schema, never your handler.

Three pitfalls catch nearly everyone: Logging to stdout (any console.log corrupts JSON-RPC; use stderr), vague descriptions (the tool gets called at the wrong moment, or never), and tool sprawl (every definition loads into the context window, so 20 to 30 tools is a sensible ceiling).

Step 3: Choose a Transport (stdio vs Streamable HTTP)

Two transports exist: Stdio (local server), where Claude Code launches your server as a child process with no ports, auth, or hosting, and Streamable HTTP (remote MCP), a hosted service many share. Use stdio here. A remote server later means an OAuth registry entry, an agreed OAuth token format with the site owner, and a health endpoint so load balancers can restart a stuck instance.

When to switch has no clean answer; some run stdio across forty laptops happily, others hit version drift within weeks.

Step 4: Test the Server with MCP Inspector

MCP Inspector is a browser-based debugger for MCP servers:

npx tsc && npx @modelcontextprotocol/inspector node build/index.js

A healthy run: Set environment variables, click Connect, List Tools shows get_ticket with its schema, and a real ID returns JSON.

Teams stall after step four, more than before. Auth, rate limits, and audit logs turn a demo into something security signs off on: the pattern behind agentic AI that auto-resolved 64% of tickets for a 400-location US retail chain.

How to Connect Your MCP Server to Claude Code

Registering the Server with claude mcp add

Options precede the name; the launch follows the double dash.

claude mcp add --transport stdio --env TICKETS_API_URL=https://tickets.internal.example.com \
  --env TICKETS_API_KEY=replace_me ticket-tools -- node /Users/priya/ticket-mcp/build/index.js
claude mcp list

Then verify: Run /mcp to see the server's status, and ask "Status of TKT-10482?" to watch Claude call get_ticket. Already set servers up in Claude Desktop? claude mcp add-from-claude-desktop imports them.

Local, Project, and User Scopes Explained

Scope decides who sees it, and the wrong choice causes early confusion; pass --scope; local is the default.

Use project scope for team servers, committing .mcp.json with secrets as ${TICKETS_API_KEY} so each developer's environment supplies them.

Letting Claude Code Build the MCP Server for You

A fintech developer we worked with spent two days reading the MCP spec just to pick a transport. Anthropic's mcp-server-dev plugin now scaffolds a model context protocol MCP server from your answers instead.

/plugin install mcp-server-dev@claude-plugins-official
/mcp-server-dev:build-mcp-server

The build command is a Claude Agent Skill that behaves like a CLI wizard: It asks what the server connects to, who uses it, and what auth applies, recommends a transport, scaffolds the project, then hands off to build-mcp-app or build-mcpb when needed. It defaults to remote Streamable HTTP for shared servers, and public ones join Anthropic's directory, where the Claude MCP Connector registry record is your shop window.

Our view: Build one by hand first, since otherwise nobody can debug what the scaffold produced.

How BuildNexTech Helps Teams Ship Production-Ready MCP Servers

BuildNexTech closes the gap between a tutorial server and one your security team actually approves. Our low-code agent builder takes teams from prototype to production in days, pairing no model lock-in with enterprise-grade observability on every tool call, built on the AI-native architecture behind our AI services.

"Our systems are too unusual," teams say. Rarely true: MCP plumbing works the same whether the client is a Claude AI agent, Claude Code, or something else, and each still needs governed tool access. Large integrators suit multi-year programmes; we suit teams wanting production within weeks.

What a BuildNexTech MCP Server Implementation Looks Like

Implementation runs in three stages, and your team owns the source, runbooks, and dashboards throughout:

• Day 1-3: We map your systems and rank them by hours saved, so the first server targets the highest-value gap.
• Day 4-7: We build and harden the servers, adding auth, rate limiting, and audit logging; security can sign off.
• Week 2: We deploy to production, monitor every tool call, and tune descriptions based on how Claude actually uses them.

Conclusion

Building an MCP server is no longer the hard part. Between the SDK, MCP Inspector, and Anthropic's mcp-server-dev plugin, a working tool takes an afternoon, not a sprint, and the pattern here scales to any REST API your team depends on.

What remains hard is governance once ten servers exist rather than one: owners, logs, and access controls for every tool call. That is the point where most teams reach for a platform instead of another script, and it is exactly where BuildNexTech starts.