Build an MCP server

What you'll build

Step-by-step build

1. 1

   Understand the protocol shape

   Read how MCP works: a client connects, asks the server what tools exist, then calls them with structured arguments and reads structured results. Knowing this request-and-response shape before coding saves a lot of confusion. The protocol, not your imagination, defines the contract.

2. 2

   Scaffold the server with the SDK

   Use the official MCP SDK to start a minimal server that runs and announces itself over stdio. Get a client to connect to it with zero tools first. A connecting empty server is your proof the transport works.

3. 3

   Register your first tool

   Add one simple tool, like a health check or an echo, with a Zod input schema and a typed result. Confirm the client discovers it and can call it. Tool discovery is the moment the protocol earns its keep.

4. 4

   Connect the real data source

   Wire in the GitHub API or your Postgres database with credentials from environment variables. Test the connection in isolation before exposing it through a tool. The data source is what makes the server useful rather than a toy.

5. 5

   Build a search tool

   Add a tool that takes a query and returns matching records with typed fields. Validate the input and shape the output so a client can render it cleanly. This is the tool that shows real value to whoever connects.

6. 6

   Build a fetch-by-id tool

   Add a second tool that returns one full record by its identifier. Having a list-then-detail pair mirrors how agents actually explore data. Test both tools from the client, not just from your own scripts.

7. 7

   Handle errors clearly

   Return structured, human-readable errors when an id is missing or the upstream call fails, rather than crashing. A client should be able to show the user what went wrong. Clean error handling is what separates a demo server from a usable one.

8. 8

   Document client registration

   Write a README that shows exactly how to add your server to Claude Desktop or Cursor, including the config entry and required environment variables. Include a screenshot of the client calling a tool. Good setup docs are what let anyone actually use your server.

Done when

• ✓A real MCP client connects and lists your tools without custom code
• ✓Both tools return typed results the client renders correctly
• ✓A bad input produces a clear error, not a crash
• ✓The server reads live data from the real source, not a hardcoded fixture
• ✓Someone can follow your README and register the server themselves

Ship it

MCP servers usually run locally next to the client, so ship it as an installable package with a README covering the client config and environment variables. If backed by Postgres, use a free Neon or Supabase database. Include one worked example of a client discovering and calling a tool.

What it proves: Shows you understand the Model Context Protocol from the server side and can make your data usable by any MCP client through the standard.

Paste this into Cursor, Claude, or ChatGPT and build it step by step.

You are my senior AI engineer pair. Help me build "Build an MCP server" step by step. MCP is the Model Context Protocol, a standard where a client connects to a server, discovers its tools, and calls them with structured arguments. A tool is a typed function the server exposes.

Stack: the official MCP SDK, Node.js and TypeScript, Zod for typed inputs and outputs, and a real data source that is either the GitHub REST API or a free Neon or Supabase Postgres. Test against a real MCP client like Claude Desktop or Cursor.

Requirements:
1. Scaffold an MCP server that a client can connect to over stdio.
2. Register tools with Zod input schemas and typed results.
3. Connect a live data source using env-var credentials.
4. Provide a search tool and a fetch-by-id tool.
5. Return clear structured errors, not crashes.

Work in this order: learn the protocol shape, scaffold an empty server, register one trivial tool, connect the data source, build search, build fetch-by-id, add error handling, then write client-registration docs. Give me commands and code for each step and STOP after each so I can test in a real client. Do not write the whole server at once.