Skip to main content

Documentation Index

Fetch the complete documentation index at: https://sunpeak.ai/docs/llms.txt

Use this file to discover all available pages before exploring further.

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.

​
See Also

Tool File

Define tool metadata, schemas, and handlers.

Deployment Guide

Production server setup and custom server integration.