bearer-mcp-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., "@bearer-mcp-server Run a diagnostic on the production API"
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.
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 |
| Echoes text back — a connectivity and auth check. |
| Search projects by name, language, status, or tags with pagination. |
| Get a single project by ID with full details including owner info. |
| Create a new project in the platform. |
| Trigger a deployment pipeline to a target environment. |
| List API keys for a project (keys are masked). |
| Rotate (regenerate) an API key — full key shown only here. |
| Get 24-hour usage and performance metrics for a project. Returns structured output. |
| Full-text search across simulated log entries with level/project filters. |
| Run a comprehensive health diagnostic on a project. Returns structured output. |
Resources (application-controlled, read-only data)
URI | Description |
| Static JSON server config, version, auth mode, and feature flags. |
| Markdown API reference for the mock developer platform. |
| Templated resource backed by mock project store (20+ projects), with listing. |
| Metrics sub-resource for a project. |
| Templated user profile resource, with listing. |
| Live system status — services, regions, and active incidents. |
Prompts (user-controlled message templates)
Prompt | Arguments | Description |
|
| Ask the model to diagnose a failed deployment. |
|
| Ask the model to generate API documentation. |
|
| Ask the model to review a configuration for security and correctness. |
|
| Ask the model to draft a blameless postmortem. |
Related MCP server: mock-mcp
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:stdioRequires 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 watchAuthentication
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 startOption 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 startOption 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-0123456789abcdefDisabling 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:smokeTesting 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 inspectFor the HTTP transport, start the server (npm run start:http) then open the Inspector and connect with:
Transport type:
Streamable HTTPURL:
http://127.0.0.1:3000/mcpHeaders: Add
Authorization: Bearer mcp-dev-token-0123456789abcdef
HTTP transport details
Method | Path | Purpose |
|
| JSON-RPC requests ( |
|
| Server-Sent Events stream for server-to-client notifications. Auth required. |
|
| Terminate a session. Auth required. |
|
| 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 interfaceExample: 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-serverCloud 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 |
|
| HTTP listen port |
|
| Listen address (Cloud Run: auto |
|
| Enforce bearer token auth on HTTP |
| — | Comma-separated valid tokens |
| — | Path to JSON file with token definitions |
|
| CORS origin for browser access |
|
| Max chars for request/response body logging |
Notes
Authentication is enforced on HTTP transport by default. Use
MCP_REQUIRE_AUTH=falseto disable for local testing.When using stdio, never write to
stdout— it is reserved for the JSON-RPC protocol. Diagnostics go tostderr(console.error).Authorization headers are redacted in log output.
License
MIT
Available Tools
10 toolscreate_projectCreate ProjectA
Create a new project in the platform. Returns the created project with its assigned ID.
Inputs: name (required), language (required), tags, region, +1 more.
deploy_serviceDeploy ServiceA
Triggers a deployment for a project to a target environment. Simulates the deployment pipeline and returns a deployment ID for tracking.
Inputs: projectId (required), branch, message, commitSha, +1 more.
echoEchoA
Echoes back the text you send. Useful as a connectivity and authentication check.
Inputs: text (required).
get_metricsGet MetricsA
Get usage and performance metrics for a project over the last 24 hours. Returns hourly data points with request counts, errors, and latency percentiles.
Inputs: projectId (required). Returns: period, points, summary, projectId
get_projectGet ProjectA
Get full details for a single project by its ID.
Inputs: projectId (required). Returns: id, name, tags, owner, +7 more
list_api_keysList API KeysA
List all API keys for a project. Keys are returned with masked values — the full key is only shown at creation time.
Inputs: projectId (required).
rotate_api_keyRotate API KeyA
Rotate (regenerate) an existing API key. The old key is immediately invalidated and a new key value is returned. This is the only time the full key is visible.
Inputs: keyId (required).
run_diagnosticRun DiagnosticA
Run a comprehensive health diagnostic on a project. Checks connectivity, recent errors, configuration validity, and resource utilization. Returns structured results.
Inputs: projectId (required). Returns: checks, overall, projectId, timestamp, +1 more
search_logsSearch LogsA
Full-text search across application log entries. Filter by project, severity level, or free-text query. Returns the most recent matching entries.
Inputs: level, limit, query, projectId.
search_projectsSearch ProjectsA
Search for projects by name, language, status, or tags. Returns paginated results with metadata.
Inputs: page, tags, limit, query, +2 more. Returns: page, limit, total, results
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Each tool targets a distinct resource and action: projects (create, get, search), deployments, API keys (list, rotate), metrics, logs, diagnostics, and connectivity. There is no overlap or ambiguity between tool purposes.
Most tools follow a clear verb_noun snake_case pattern (create_project, search_logs, rotate_api_key). The only deviation is 'echo', which lacks a noun object, but this is a minor utility and does not undermine the overall pattern.
With 10 tools, the server is well-scoped for a platform management API. Each tool covers a distinct aspect of project and deployment management, observability, and diagnostics, without unnecessary bloat.
The server covers project creation, retrieval, search, and deployment, but lacks update/delete operations for projects and API key creation/deletion. Deployment status tracking is also missing. These are notable gaps that agents may need to work around.
Related MCP Connectors
The official MCP Server for the Mux API
One OAuth connector for your team's remote MCP servers, with Tool Packs, guardrails and logs.
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
MCP server for StyleKit styles, tokens, recipes, lint and repair over stdio or HTTP.
Related MCP Servers
- AlicenseBqualityDmaintenanceA mock MCP server for testing MCP client implementations and development workflows. Supports tools, prompts, and resources across multiple transport protocols (stdio, HTTP, SSE).1MIT
- FlicenseNot gradedqualityDmaintenanceA minimal local HTTP MCP mock server for development and testing, providing predictable tool responses with OAuth token support and zero dependencies.-
- FlicenseNot gradedqualityCmaintenanceAn MCP server with HTTP/stdio support, a web admin panel for managing services, capabilities, and user permissions with Bearer token authentication, enabling relay and access control for MCP tools.-
- FlicenseNot gradedqualityDmaintenanceThis MCP server provides a Streamable HTTP endpoint with bearer token authentication, exposing echo and add tools, and an info resource for remote client integration.-