my-first-server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@my-first-server What's the current time in Tokyo?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
My First MCP Server
A minimal Model Context Protocol server that
exposes a single tool, get_current_time, over stdio. Built with the
TypeScript SDK.
Use it as a learning reference for how an MCP server is structured and how it connects to hosts like Claude Code and the Claude desktop app.
📚 See
docs/transports.mdfor notes on stdio vs HTTP transports, "Streamable HTTP," and the stateless spec update (2026-07-28) that removedMcp-Session-Idand the handshake.
How it works
An MCP host (Claude Code, the Claude desktop app) launches this server
as a child process and talks to it over stdin/stdout using newline-delimited
JSON-RPC. The server advertises its tools; when the model decides to use one,
the host sends a tools/call request, the handler runs, and the result flows
back into the model's context.
Claude (host) <--- JSON-RPC over stdio ---> node dist/index.js (this server)stdio gotcha: stdout is the JSON-RPC channel. Never
console.login a stdio server — it corrupts the protocol stream. Log to stderr withconsole.error(visible viaclaude --debugor the Inspector).
Key files:
File | Purpose |
| The tool definition ( |
| stdio entrypoint (what Claude Code / desktop launch). |
| Streamable HTTP entrypoint (Express, stateless, |
| Demo client — connects to the HTTP server, lists + calls the tool. |
| Registers the server with Claude Code (project scope, committed). Uses a relative path so it works on any machine. |
|
|
| Compiled output. Git-ignored — regenerated by the build. |
| Notes on stdio vs HTTP transports and the stateless spec update. |
Related MCP server: mcp-timer-server
Setup
The Node version is pinned in .nvmrc. Select it first (installs it if needed):
nvm use # reads .nvmrc; run `nvm install` first if that version is missing
npm install # installs deps AND builds dist/ (via the "prepare" script)nvm use + npm install is all a fresh clone needs before the server is
runnable.
Use cases
1. Local development — fast edit/test loop
Run straight from TypeScript source, no build step, using tsx:
npm run devOr compile and run the built output (what the hosts actually execute):
npm run build # tsc -> dist/
npm start # node dist/index.jsRebuild after editing src/ if you're testing through a host, since hosts run
the compiled dist/index.js.
Tip: for a zero-build inner loop, you can point
.mcp.jsonat"command": "npx", "args": ["tsx", "src/index.ts"]so the host runs the TypeScript directly. Switch back todist/index.jsfor a "production" run.
2. Run the HTTP server + demo client
The same tool, served over Streamable HTTP instead of stdio. Start the server (it runs on its own; a host connects by URL), then run the client in a second terminal:
npm run start:http # -> http://localhost:3000/mcp (or npm run dev:http)
npm run client # connects, lists tools, calls get_current_timeThe server is stateless (no Mcp-Session-Id): each POST /mcp builds a
fresh server + transport. See docs/transports.md for why.
By default it replies over SSE so it can stream progress notifications
(see the stream_load tool). Set MCP_JSON=1 for single plain-JSON replies
(easier for curl, but no streaming):
MCP_JSON=1 npm run start:http
curl -s -X POST http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'To watch the raw SSE stream (progress events, then the final result), run the
server in default SSE mode and see the streaming example in
docs/transports.md.
To connect Claude Code to the HTTP server instead of stdio:
claude mcp add --transport http my-http-server http://localhost:3000/mcp3. Inspect & debug with the MCP Inspector
The official Inspector is a standalone host with a UI — the fastest way to see your tools, call them, and read stderr logs without involving Claude:
npx @modelcontextprotocol/inspector node dist/index.jsIt opens a local web UI where you can run the initialize handshake, browse
tools/list, and invoke get_current_time with arguments.
4. Test the raw protocol by hand
This is exactly what a host does — feed it the three startup messages and a call:
printf '%s\n%s\n%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}' \
'{"jsonrpc":"2.0","method":"notifications/initialized"}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_current_time","arguments":{"timezone":"Asia/Kolkata"}}}' \
| node dist/index.js 2>/dev/null5. Connect to Claude Code
.mcp.json is committed, so Claude Code picks the server up automatically:
cd <this-project>
claude # start a session in the project dirOn first launch, approve the my-first-server prompt (remembered per project).
Then inside the session:
/mcp # verify: my-first-server -> connected, 1 tool
what time is it in Tokyo right now? # triggers get_current_timeDebug connection issues with:
claude --debug # shows the handshake and the server's stderr logs6. Connect to the Claude desktop app
The desktop app's config is machine-local (not in this repo). On macOS it lives at:
~/Library/Application Support/Claude/claude_desktop_config.jsonAdd an entry under mcpServers pointing at this machine's absolute path to
dist/index.js:
{
"mcpServers": {
"my-first-server": {
"command": "node",
"args": ["/absolute/path/to/this/repo/dist/index.js"]
}
}
}Then fully quit (Cmd+Q) and reopen the app — config is only read at startup. Look for the tools icon and ask the same time question.
After you push to GitHub
Committed: src/, package.json, package-lock.json, tsconfig.json,
.mcp.json, README.md, .gitignore.
Not committed (regenerated per machine): node_modules/, dist/, and the
Claude desktop config (it's outside the repo).
So a teammate cloning the repo just runs:
git clone <repo> && cd <repo>
npm install # builds dist/ automatically
claude # Claude Code auto-detects .mcp.json; approve onceThe desktop app is the only piece they re-register locally (use case 6), because its config uses an absolute path unique to their machine.
Publishing to npm (@srav/mcp-time-server)
Publishing lets anyone add the server with a single npx line — no clone, no
build, no absolute paths.
Prerequisites already in place:
binmapsmy-mcp-server → dist/index.js, andsrc/index.tsstarts with#!/usr/bin/env node, so the published package is directly runnable.files: ["dist"]ensures the compiled output ships in the tarball. (Without it, npm falls back to.gitignore— which excludesdist/— and would publish an empty package.)preparebuildsdist/automatically onnpm publish.publishConfig.access = "public"publishes the scoped package publicly.
Verify, then publish:
npm pack --dry-run # confirm dist/index.js is in the tarball
npm login # once
npm publish # runs prepare (build) then uploadsAfter publishing, switch .mcp.json (or use claude mcp add) from the local
path to the published package:
// local dev (current — keep while iterating)
{ "command": "node", "args": ["dist/index.js"] }
// published (after npm publish)
{ "command": "npx", "args": ["-y", "@srav/mcp-time-server"] }# or register from the CLI, user scope = available in every project
claude mcp add --scope user my-first-server -- npx -y @srav/mcp-time-servernpx downloads the package to its cache on first run, then executes the bin
entry — from there the stdio JSON-RPC flow is identical to running locally.
Distribution models at a glance
Model |
| When |
Local path |
| You, developing on this machine |
Cloned repo |
| Teammates who clone + |
Published npm |
| Anyone, anywhere — no clone needed |
Available Tools
2 toolsget_current_timeGet current timeA
Returns the current date and time. Optionally pass an IANA timezone (e.g. 'Asia/Kolkata', 'America/New_York') to get the time there.
Inputs: timezone. Returns: iso, timezone, unixSeconds
stream_loadStreaming load demoA
Simulates loading in steps, streaming one progress notification per step, then returns a final message.
Inputs: steps.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 2 tools
The two tools are completely unrelated in function—one returns time and the other simulates streaming—so there is zero ambiguity about which to choose. No overlap or boundary confusion exists.
Both tool names follow a clear snake_case verb_noun pattern: get_current_time and stream_load. The naming is predictable and consistent, even if the verbs are not from the same domain.
With only two tools, the set feels thin and barely qualifies as a server. It's on the borderline of the acceptable range for a minimal utility or demo server.
The tools do not belong to a shared domain, so there is no meaningful coverage to assess. Each tool is an isolated snippet with no related operations, leaving the server's purpose unclear and incomplete.
Related MCP Connectors
Timezone MCP — wraps timeapi.io (free, no auth)
A real clock for AI agents: current time, timezone conversion, and DST facts from the IANA tzdb.
Current time, timezone conversion & date math for AI agents. On Cloudflare Workers.
Current time in any IANA time zone, plus the full time-zone list. Via timeapi.io.
Related MCP Servers
- AlicenseDqualityCmaintenanceA lightweight MCP server that provides date and time tools, including the ability to retrieve current timestamps and parse date strings with IANA timezone support. It enables AI models to interact with the host OS clock and perform temporal calculations via stdio transport.311 npm7MIT
- AlicenseAqualityDmaintenanceProvides accurate system time to LLM applications with multi-timezone support via a simple tool call.1MIT
- AlicenseNot gradedqualityDmaintenanceA remote MCP server exposing date/time tools over Streamable HTTP, enabling retrieval of current time for IANA timezones and listing available timezones, designed for use with web clients like Claude.ai.MIT
- AlicenseAqualityDmaintenanceA local MCP server that converts timestamps between time zones using IANA time zone rules, exposing a single convert_time tool.1MIT