Server Entry - sunpeak

sunpeak API

Overview

The optional src/server.ts file configures authentication and server metadata. When present, the framework calls auth() on every MCP request and populates extra.authInfo in tool handlers. Under the hood, the returned AuthInfo is set as req.auth on the HTTP request — the same mechanism the MCP SDK uses. This gives you the same flexibility as using the SDK directly.

File Convention

src/server.ts

Example

// src/server.ts

import type { IncomingMessage } from 'node:http';
import type { AuthInfo } from 'sunpeak/mcp';

export async function auth(req: IncomingMessage): Promise<AuthInfo | null> {
  const token = req.headers.authorization?.replace('Bearer ', '');
  if (!token) return null; // Reject → 401 Unauthorized
  return { token, clientId: 'sunpeak-app', scopes: [] };
}

export const server = { name: 'My App', version: '1.0.0' };

Exports

`auth` (function, optional)

Called on every MCP request. Return AuthInfo to authenticate, or null to reject the request with 401.

export async function auth(req: IncomingMessage): Promise<AuthInfo | null> {
  const token = req.headers.authorization?.replace('Bearer ', '');
  if (!token) return null;
  // Verify however you want — JWT, database, external API
  const user = await verifyToken(token);
  return { token, clientId: user.id, scopes: user.scopes };
}

req

IncomingMessage

required

The incoming HTTP request from Node’s http module. Access headers, cookies, query params, etc.

Returns AuthInfo | null (sync or async):

interface AuthInfo {
  token: string;
  clientId: string;
  scopes: string[];
  expiresAt?: number;           // Unix timestamp
  resource?: URL;               // RFC 8707 resource identifier
  extra?: Record<string, unknown>; // Custom data
}

Return null to reject the request — Sunpeak responds with 401 Unauthorized and a WWW-Authenticate: Bearer header.

`server` (object, optional)

Server metadata reported to hosts during the MCP handshake.

export const server = { name: 'My App', version: '1.0.0' };

name

string

Server name displayed in the host.

version

string

Server version.

title

string

Human-readable display name. Shown by hosts when more polish is needed than name.

description

string

Short description of what the server does.

websiteUrl

string

URL of the server’s homepage.

icons

Icon[]

64x64 PNG icons (data URIs preferred). Light and dark variants supported via the theme field on each icon.

instructions

string

Server-wide instructions sent in the MCP initialize response. Hosts (ChatGPT, Claude) may surface this to the model, typically by injecting it into the system prompt. Use it for guidance that spans multiple tools or describes the server as a whole — e.g., “Always call get_user before update_user” or “This server is read-only between 5pm and 9am UTC”. Per-tool guidance still belongs in each tool’s description.

export const server: ServerConfig = {
  name: 'My App',
  version: '1.0.0',
  instructions: 'Call list_orders before fulfill_order. Refunds require a manager scope.',
};

Using Auth in Tool Handlers

The authInfo from the server entry is available in every tool handler:

// src/tools/show-albums.ts

export default async function (args: Record<string, unknown>, extra: ToolHandlerExtra) {
  const token = extra.authInfo?.token;
  const data = await fetchAlbums(token, args.category);
  return { structuredContent: data };
}

Custom Server

If you need middleware, custom routes, or full control over the HTTP server, use createMcpHandler (Node.js) or createHandler (Web Standard) to mount the MCP protocol on your own server:

import { createMcpHandler } from 'sunpeak/mcp';

// Node.js — mount on Express, Fastify, vanilla http.createServer
const mcpHandler = createMcpHandler({ tools, resources, auth });

import { createHandler } from 'sunpeak/mcp';

// Web Standard — Cloudflare Workers, Deno, Bun, Vercel Edge
const handler = createHandler({ tools, resources, auth });

These handlers accept pre-loaded tool and resource objects — they don’t auto-discover from dist/. See the Production Server API for config types and the Deployment Guide for complete examples.

Tool File

Define tool metadata, schemas, and handlers.

Deployment Guide

Production server setup and custom server integration.

​Overview

​File Convention

​Example

​Exports

​auth (function, optional)

​server (object, optional)

​Using Auth in Tool Handlers

​Custom Server

​See Also

Tool File

Deployment Guide

Overview

File Convention

Example

Exports

`auth` (function, optional)

`server` (object, optional)

Using Auth in Tool Handlers

Custom Server

See Also