Skip to main content
Glama
agarcia-seidor

http-mcp-server

by agarcia-seidor
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

MCP Mock HTTP

Mock HTTP server for MCP-style clients.

Quick path

  1. Put PORT and MCP_NAME in .env at the repo root.

  2. Run pnpm dev or pnpm start.

  3. Open http://localhost:<PORT>/health or connect a client to http://localhost:<PORT>/mcp.

Related MCP server: MCP HTTP Server Demo

Runtime configuration

Source

Behavior

.env in the repo root

Loaded by src/server.ts before env parsing

Shell environment

Takes precedence over .env values

src/config/env.ts

Validates PORT and MCP_NAME, then applies defaults

Variable

Default

Purpose

PORT

3000

HTTP listen port

MCP_NAME

mcp-mock

MCP server name and health payload name

Tenant request configuration

Each MCP HTTP request can carry its own tenant API settings through headers:

Header

Example

Purpose

X-Api-Url

https://api.example.com/v1

Base URL for the tenant API

Authorization

Bearer pat_123

Tenant PAT / bearer token

Send both headers on each MCP request that needs tenant-aware tools. The server validates the headers per request and exposes the parsed config to tools through request context.

Mock tenant-aware tool

mock-api-ping is a safe stand-in for a real external integration.

Behavior

What you should see

Valid X-Api-Url + Authorization: Bearer ...

A JSON response with the tenant API URL, bearerTokenPresent: true, and a simulated GET /ping summary.

Missing or invalid tenant headers

A tool error with a clear header validation message.

Secret token value

Never returned by the tool.

Versioning

Source

Purpose

package.json

Single source of truth for the server version

src/version.ts

Runtime accessor used by the MCP server and tests

CHANGELOG.md

Repository-level release tracking

When reusing this repository as a base for another MCP server, update the package version and add a changelog entry before the first release.

Requirements

  • Node.js 26.0.0

  • pnpm

Install

pnpm install

Run

pnpm dev

The server bootstrap loads .env automatically, so local values apply without exporting them in the shell.

Build

pnpm build

Docker

Build the production image:

docker build -t mcp-server .

Run it with runtime environment variables:

docker run --rm -p 3000:3000 --env-file .env mcp-server

Override values at runtime when needed:

docker run --rm -p 3000:3000 -e PORT=8080 -e MCP_NAME=my-mcp mcp-server

The image does not contain your .env file. That keeps secrets out of the image while still letting the server read .env-style values if you provide them at runtime.

Quality checks

pnpm typecheck
pnpm lint
pnpm test
pnpm coverage
pnpm format

pnpm coverage runs Vitest with the v8 coverage provider and prints a coverage summary in the terminal.

Endpoints

  • GET /health — JSON health response with ok, name, and uptime.

  • /mcp* — MCP streamable HTTP transport handled by the SDK bridge.

  • mock-api-ping — mock tenant-aware tool that verifies request-scoped tenant config without calling an external API.

MCP Inspector

Use the Inspector as a client against the running HTTP server:

  1. Start this project.

  2. Launch the Inspector:

    npx @modelcontextprotocol/inspector

  3. In the Inspector, choose the Streamable HTTP transport and connect to http://localhost:<PORT>/mcp.

  4. Verify the connection by listing tools or calling one of the registered tools.

Project structure

  • src/server.ts — process bootstrap only

  • src/app.ts — HTTP server composition and routing

  • src/config/env.ts — environment parsing and validation

  • src/http/routes/health.ts — health route handler

  • src/mcp/create-server.ts — MCP server construction and tool registration

  • src/mcp/request-config.ts — request-scoped tenant config extraction and lookup helpers

  • src/version.ts — runtime version resolution from package.json

  • src/mcp/tools/echo.ts — echo tool registration

  • src/mcp/tools/mock-api-ping.ts — mock tenant-aware tool

  • src/mcp/tools/time.ts — time tool registration

  • src/mcp/transport.ts — Node HTTP to MCP transport bridge

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Mock MCP Server

    DiscreteTom
    A
    license
    B
    quality
    D
    maintenance
    A mock MCP server for testing MCP client implementations and development workflows. Supports tools, prompts, and resources across multiple transport protocols (stdio, HTTP, SSE).
    1
    MIT

  • MCP HTTP Server Demo

    MLValidationDebug
    F
    license
    Not graded
    quality
    D
    maintenance
    A minimal Model Context Protocol (MCP) server that uses streamable HTTP transport to provide demo tools for calculations, notes, and time. It serves as a standalone example for testing MCP connectivity and gateway registration through a standard HTTP endpoint.
    -

  • helloworld-demo-mcp

    Jasonrve
    F
    license
    Not graded
    quality
    D
    maintenance
    A minimal MCP server offering a hello_world tool that returns a greeting and current UTC time via streamable HTTP.
    -