Helvetium MCP

Standalone TypeScript implementation of Model Context Protocol 2026-07-28. It is designed to let AI agents communicate with Helvetium Boot services or any Fetch/stdin-stdout host without importing the official MCP SDK.

Protocol model

MCP 2026-07-28 is stateless at the protocol layer. Helvetium MCP implements this futuristic stateless architecture natively, but it also features a built-in backward-compatibility layer. It seamlessly handles legacy initialize handshakes and omits the need for _meta fields when communicating with older standard clients. This means it works out-of-the-box with both stateful 2024-11-05 clients and stateless 2026-07-28 clients. Every request in the new protocol carries its protocol version and client capabilities in _meta. The optional server/discover call exposes server capabilities. Streamable HTTP requests mirror routing data in MCP-Protocol-Version, Mcp-Method, Mcp-Name, and optional Mcp-Param-* headers.

Install

npm install @newfoundcodes/helvetium-mcp

Helvetium Boot is optional:

npm install @newfoundcodes/helvetium-boot

Minimal server

import { MCPServer, type McpTool } from '@newfoundcodes/helvetium-mcp';

const mcpServer = new MCPServer({
  name: 'my-mcp-server',
  version: '1.0.0',
});

// Define tools cleanly using the McpTool type
export function pingTool(): McpTool {
  return {
    description: 'Ping tool to check server status',
    inputSchema: { type: 'object', properties: {}, additionalProperties: true },
    handler: async (args, context) => {
      return {
        status: 'pong',
      };
    },
  };
}

mcpServer.tool('ping', pingTool());

Helvetium Boot

In a standard Helvetium project generated by the CLI, an MCP server is already scaffolded inside src/routes/paths.ts and mounted on the /mcp route using mountMCP. An example tool is generated in src/routes/mcp/ping.ts.

To manually wire an MCP server into a Helvetium Boot application:

import { createApp } from '@newfoundcodes/helvetium-boot';
import { createMCPServer, mountMCP } from '@newfoundcodes/helvetium-mcp';

const app = createApp();
const mcp = createMCPServer({ name: 'boot-mcp', version: '1.0.0' });
mcp.tool('health', () => ({ healthy: true }));
mountMCP(app, mcp, { path: '/mcp' });

Security

MCP metadata does not authorize a request. Protect sensitive tools and resources with real identity and object-level authorization. Validate OAuth/JWT tokens before handlers run, use TLS, restrict Origins for browser-accessible HTTP endpoints, apply body/time/rate limits, honor cancellation, and never forward the caller's bearer token blindly to upstream systems.

JSON Schema note

Tool schemas remain ordinary JSON Schema on the MCP wire. The dependency-free built-in validator covers common structural and constraint keywords and is used for basic input/output checking. It is not presented as a complete general JSON Schema 2020-12 engine. Applications that depend on advanced schema keywords should perform an additional validation pass with their chosen standards-complete validator.

Authoritative MCP baseline

• https://modelcontextprotocol.io/specification/2026-07-28
• https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/schema/2026-07-28/schema.ts
• https://blog.modelcontextprotocol.io/posts/2026-07-28/

License

This project is licensed under the AGPL-3.0-only License.