adamd9/mcp-reference

MCP Reference Server

A minimal, self-contained Model Context Protocol (MCP) HTTP server you can copy into other Node.js projects.

It exposes a single /mcp endpoint via Express and implements three reference tools:

• ping — health check returning a timestamp.
• echo — echos a provided message.
• get_time — returns current time in UTC and optionally a specified IANA timezone.

Prerequisites

• Node.js 18+

Quick start

# From this folder
npm install
npm start
# Server starts on http://localhost:3002

Test with MCP Inspector (HTTP transport):

# GUI mode (may open a browser window)
npx @modelcontextprotocol/inspector --transport http --server-url http://localhost:3002/mcp

Project structure

mcp-reference/
├── package.json
├── README.md
├── .gitignore
├── mcp-inspector.config.json
└── src/
    └── index.js

How it works

• src/index.js creates an Express app and an MCP server from @modelcontextprotocol/sdk.
• The /mcp route uses StreamableHTTPServerTransport to bridge HTTP requests to the MCP server and supports POST (JSON-RPC), GET (SSE), and DELETE (session close) per the Streamable HTTP transport.
• Tools are registered via server.registerTool(name, {title, description, inputSchema}, handler).
• Tool handlers resolve to { content: [{ type: 'text', text: string }] }, which MCP clients will display.

Environment variables

• PORT (optional): server port. Defaults to 3002.
• MCP_AUTH_CODE (optional): if set, the server requires mcp-auth-code: <code> on all /mcp routes.

Integrating into another project

1. Copy the src/index.js and package.json dependencies into your project.
2. Mount the /mcp route in your existing Express server (or use this file as a separate service).
3. Register your own tools using the registerTool pattern shown in src/index.js.

Example tool registration

server.registerTool(
  'hello_name',
  {
    title: 'Hello Name',
    description: 'Returns a personalized greeting.',
    inputSchema: { name: z.string().describe('Name to greet') }
  },
  async ({ name }) => ({
    content: [{ type: 'text', text: JSON.stringify({ greeting: `Hello, ${name}!` }, null, 2) }]
  })
);

Notes

• This reference intentionally avoids any databases, external APIs, or auth. Add those in your own project as needed.
• For full capabilities and protocol details, see the MCP SDK docs.

Troubleshooting MCP Inspector

• If Inspector tries to start a demo STDIO server (e.g., mcp-server-everything) or connects to the wrong port (e.g., 3001), force HTTP transport and URL:

  npx @modelcontextprotocol/inspector --transport http --server-url http://localhost:3002/mcp
  

• If you get a proxy/UI port conflict like Proxy Server PORT IS IN USE at port 6277, close any previous Inspector instances. On macOS, you can find and kill the process:

  lsof -i :6277
  kill -9 <PID>
  

  Note: The Inspector CLI currently expects stdio transport for local commands, so prefer the GUI with --transport http and --server-url when testing HTTP servers.

Enabling basic auth for the MCP server

You can enable a simple shared-secret check on the MCP routes by setting an environment variable. When enabled, requests to POST /mcp, GET /mcp (SSE), and DELETE /mcp must include this header with the exact secret value:

• mcp-auth-code: <your-secret>

Set the secret and start the server:

export MCP_AUTH_CODE="my-secret-123"
npm start

Test with curl:

# Initialize (example JSON-RPC payload), passing the header
curl -sS \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-auth-code: my-secret-123" \
  -d '{"jsonrpc":"2.0","id":"1","method":"initialize","params":{"protocolVersion":"2025-03-26"}}' \
  http://localhost:3002/mcp

Run MCP Inspector with the header:

# Option 1: pass the header inline
npx @modelcontextprotocol/inspector \
  --transport http \
  --server-url http://localhost:3002/mcp \
  --header "mcp-auth-code: my-secret-123"

# Option 2: use env var with the npm script
export MCP_AUTH_CODE="my-secret-123"
npm run mcp:debug:auth