Skip to main content
Glama
README.md
<div align="center">
  <img src="https://github.com/newfoundcodes/newfoundcodes-logo/blob/main/newfoundcodes-helvetium.png?raw=true" width="128" />
  <h1>Helvetium MCP</h1>
  <p>
    <a href="https://github.com/newfoundcodes/helvetium-mcp/actions"><img src="https://github.com/newfoundcodes/helvetium-mcp/actions/workflows/ci.yml/badge.svg" alt="Build Status"></a>
  </p>
</div>

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

```bash
npm install @newfoundcodes/helvetium-mcp
```

Helvetium Boot is optional:

```bash
npm install @newfoundcodes/helvetium-boot
```

## Minimal server

```typescript
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:

```ts
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](https://spdx.org/licenses/AGPL-3.0-only.html) License.