@forgedevstack/forge-mcp

Tiny helper for building API-key-protected stdio MCP servers. Wraps the official @modelcontextprotocol/sdk so you define tools with plain JSON schemas — no zod, no boilerplate — and get a working server with one call.

Part of the ForgeStack family of libraries.

Install

npm install @forgedevstack/forge-mcp

A working MCP server in under 20 lines

import { createMcpServer, textResult } from '@forgedevstack/forge-mcp';

const { start } = createMcpServer({
  name: 'my-server',
  version: '1.0.0',
  apiKey: { envVar: 'MY_API_KEY' },
  tools: [
    {
      name: 'echo',
      description: 'Echo a message',
      inputSchema: { type: 'object', properties: { message: { type: 'string' } }, required: ['message'] },
      handler: (args) => textResult(String(args.message)),
    },
  ],
});

start();

API

createMcpServer(options): ForgeMcpServer

| Option | Type | Description | |---|---|---| | name | string | Server name reported to MCP clients | | version | string | Server version reported to MCP clients | | tools | McpToolDefinition[] | Tools exposed via tools/list and tools/call | | apiKey | ApiKeyConfig (optional) | API key resolution; omit if no key is needed |

Returns { server, apiKey, start }:

• server — the underlying SDK Server instance for advanced use
• apiKey — the resolved API key (pass it to your API clients inside handlers)
• start() — connects a StdioServerTransport and begins serving

The API key is resolved eagerly, so a misconfigured server fails fast at startup instead of on the first tool call.

Tool definition

interface McpToolDefinition {
  name: string;
  description: string;
  inputSchema: JsonSchema;
  handler: (args: Record<string, unknown>) => Promise<McpToolResult> | McpToolResult;
}

inputSchema is a plain JSON schema object (type, properties, required, items, enum, ...). Handler exceptions are caught and returned as isError results, and calls to unknown tool names return an isError result instead of crashing the server.

API key config

interface ApiKeyConfig {
  envVar?: string;
  value?: string;
  required?: boolean;
}

Precedence: value first, then process.env[envVar] (default env var: MCP_API_KEY). When apiKey is passed and the key is missing, createMcpServer throws unless required: false.

Helpers

• textResult(text) — { content: [{ type: 'text', text }] }
• errorResult(text) — same, with isError: true
• resolveApiKey(config) — standalone key resolution, same rules as above
• DEFAULT_API_KEY_ENV_VAR — 'MCP_API_KEY'

Wiring into an MCP client

Point your MCP client (Cursor, Claude Desktop, etc.) at your server script and pass the key through env:

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["/path/to/my-server.js"],
      "env": { "MY_API_KEY": "your-key-here" }
    }
  }
}

License

MIT