bearer-mcp-server

A production-style Model Context Protocol (MCP) server with bearer token authentication, written in TypeScript with the official @modelcontextprotocol/sdk.

It demonstrates all three core MCP primitives — tools, resources, and prompts — themed as a developer platform API with mock data (projects, deployments, API keys, metrics, logs, diagnostics).

Compatible with MCP protocol versions 2025-11-25 and 2026-07-28.

It supports two transports out of the box:

• stdio — for desktop clients (Claude Desktop, MCP Inspector launching a subprocess). No auth.
• Streamable HTTP — for HTTP-based clients, with session management and bearer token authentication.

---

What's inside

Tools (model-controlled actions)

Tool	Description
echo	Echoes text back — a connectivity and auth check.
search_projects	Search projects by name, language, status, or tags with pagination.
get_project	Get a single project by ID with full details including owner info.
create_project	Create a new project in the platform.
deploy_service	Trigger a deployment pipeline to a target environment.
list_api_keys	List API keys for a project (keys are masked).
rotate_api_key	Rotate (regenerate) an API key — full key shown only here.
get_metrics	Get 24-hour usage and performance metrics for a project. Returns structured output.
search_logs	Full-text search across simulated log entries with level/project filters.
run_diagnostic	Run a comprehensive health diagnostic on a project. Returns structured output.

Resources (application-controlled, read-only data)

URI	Description
config://server	Static JSON server config, version, auth mode, and feature flags.
docs://api-reference	Markdown API reference for the mock developer platform.
projects://{id}	Templated resource backed by mock project store (20+ projects), with listing.
projects://{id}/metrics	Metrics sub-resource for a project.
users://{id}	Templated user profile resource, with listing.
status://system	Live system status — services, regions, and active incidents.

Prompts (user-controlled message templates)

Prompt	Arguments	Description
debug_deployment	projectName, errorMessage, environment	Ask the model to diagnose a failed deployment.
write_api_docs	endpoint, language, includeExamples	Ask the model to generate API documentation.
review_config	configType, configYaml	Ask the model to review a configuration for security and correctness.
incident_postmortem	service, severity, summary, duration	Ask the model to draft a blameless postmortem.

---

Quick start

# 1. Install dependencies
npm install

# 2. Build the TypeScript
npm run build

# 3a. Run over Streamable HTTP (with bearer auth)
npm start

# 3b. ...or run over stdio for desktop clients
npm run start:stdio

Requires Node.js >= 18.

Development (no build step, auto-reload)

npm run dev:stdio   # stdio transport with tsx watch
npm run dev:http    # HTTP transport with tsx watch

---

Authentication

The HTTP transport requires a Bearer token on all /mcp requests:

Authorization: Bearer <token>

The /health endpoint is exempt from authentication.

Configuring tokens

Option 1: Environment variable (simple)

# macOS / Linux
MCP_BEARER_TOKENS=sk_abc123,sk_def456 npm start

# Windows PowerShell
$env:MCP_BEARER_TOKENS="sk_abc123,sk_def456"; npm start

Option 2: Token file (rich — with scopes and names)

[
  { "token": "sk_abc123", "name": "ci-pipeline", "scopes": ["read:*", "write:deployments"] },
  { "token": "sk_def456", "name": "readonly-dashboard", "scopes": ["read:*"] }
]

MCP_TOKEN_FILE=./tokens.json npm start

Option 3: Default dev token (zero-config)

When neither MCP_BEARER_TOKENS nor MCP_TOKEN_FILE is set, a single dev token is available:

mcp-dev-token-0123456789abcdef

Disabling authentication

MCP_REQUIRE_AUTH=false npm start

⚠️ Only disable auth for local testing behind trusted networks.

stdio transport

Authentication is not enforced on the stdio transport — it runs as a local subprocess spawned by the MCP client.

---

Testing

Run the local smoke test to build the server, start it over stdio, and verify the expected tools, resources, resource templates, and prompts:

npm run test:smoke

Testing with the MCP Inspector

The MCP Inspector is the easiest way to explore the server:

# Launches the Inspector and this server (stdio) together
npm run inspect

For the HTTP transport, start the server (npm run start:http) then open the Inspector and connect with:

• Transport type: Streamable HTTP
• URL: http://127.0.0.1:3000/mcp
• Headers: Add Authorization: Bearer mcp-dev-token-0123456789abcdef

---

HTTP transport details

Method	Path	Purpose
POST	/mcp	JSON-RPC requests (initialize + all subsequent calls). Auth required.
GET	/mcp	Server-Sent Events stream for server-to-client notifications. Auth required.
DELETE	/mcp	Terminate a session. Auth required.
GET	/health	Plain health check (not part of MCP). No auth required.

Sessions are tracked via the Mcp-Session-Id response/request header. The HTTP server binds to 127.0.0.1 by default, and the port defaults to 3000. Both can be overridden:

PORT=3100 npm run start:http                 # macOS / Linux
HOST=0.0.0.0 PORT=3100 npm run start:http    # macOS / Linux, public interface
$env:PORT=3100; npm run start:http           # Windows PowerShell
$env:HOST="0.0.0.0"; npm run start:http      # Windows PowerShell, public interface

Example: raw HTTP handshake with curl

curl -i -X POST http://127.0.0.1:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer mcp-dev-token-0123456789abcdef" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"1.0.0"}}}'

The response includes an Mcp-Session-Id header — pass it back as a request header on subsequent calls.

Testing auth failure

Omitting the token or using an invalid one returns:

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32001,
    "message": "Unauthorized: missing Bearer token in Authorization header"
  },
  "id": null
}

---

Deployment

Docker / Google Cloud Run

docker build -t bearer-mcp-server .
docker run -p 8080:8080 \
  -e MCP_BEARER_TOKENS=your_token_here \
  bearer-mcp-server

Cloud Run sets the PORT environment variable and requires the container to listen on 0.0.0.0:$PORT. The server detects Cloud Run via K_SERVICE and auto-binds appropriately.

Vercel

The api/ directory contains serverless MCP and health handlers. Deploy with the Vercel Git integration or CLI — set the Framework Preset to Other and leave Build Command / Output Directory empty.

---

Using it with Claude Desktop

Add this to your claude_desktop_config.json (use the absolute path to dist/stdio.js):

{
  "mcpServers": {
    "bearer-mcp-server": {
      "command": "node",
      "args": ["C:\\Users\\Shylendra\\git\\bearer-mcp-server\\dist\\stdio.js"]
    }
  }
}

Restart Claude Desktop, and the server's tools, resources, and prompts will appear.

---

Project layout

src/
├── server.ts          # createServer() factory + ServerCatalog
├── tools/             # Tool definitions (split by domain)
│   ├── index.ts       # registerTools() aggregator
│   ├── projects.ts    # search_projects, get_project, create_project
│   ├── deployments.ts # deploy_service
│   ├── api-keys.ts    # list_api_keys, rotate_api_key
│   ├── monitoring.ts  # get_metrics, search_logs, run_diagnostic
│   └── echo.ts        # echo tool
├── resources/
│   └── index.ts       # registerResources() — all 6 resources
├── prompts/
│   └── index.ts       # registerPrompts() — all 4 prompts
├── auth/
│   ├── middleware.ts  # Express bearer-token middleware
│   └── tokens.ts      # Token store, validation, loading
├── data/              # Mock data stores
│   ├── projects.ts    # 20 mock projects
│   ├── users.ts       # 5 mock user profiles
│   ├── api-keys.ts    # 8 mock API keys
│   ├── metrics.ts     # Deterministic metrics generator
│   ├── logs.ts        # Deterministic log generator
│   └── system.ts      # System status with incidents
├── stdio.ts           # stdio transport entry point
├── http.ts            # Streamable HTTP transport entry point (with auth)
├── banner.ts          # ANSI startup banner
└── logging.ts         # Structured JSON logging with redaction
api/
├── mcp.ts             # Vercel serverless MCP handler (with auth)
└── health.ts          # Vercel health check
index.ts               # Root HTTP router (node:http)

Environment variables

Variable	Default	Description
PORT	3000	HTTP listen port
HOST	127.0.0.1	Listen address (Cloud Run: auto 0.0.0.0)
MCP_REQUIRE_AUTH	true	Enforce bearer token auth on HTTP
MCP_BEARER_TOKENS	—	Comma-separated valid tokens
MCP_TOKEN_FILE	—	Path to JSON file with token definitions
MCP_CORS_ORIGIN	*	CORS origin for browser access
MCP_LOG_BODY_LIMIT	4000	Max chars for request/response body logging

Notes

• Authentication is enforced on HTTP transport by default. Use MCP_REQUIRE_AUTH=false to disable for local testing.
• When using stdio, never write to stdout — it is reserved for the JSON-RPC protocol. Diagnostics go to stderr (console.error).
• Authorization headers are redacted in log output.

License

MIT