Interface: StartServerOptions<TContext> ​

Defined in: packages/core/src/server/startServer.ts:36

Options for startServer.

Type Parameters ​

Type Parameter
TContext

Properties ​

attach? ​

ts
readonly optional attach: Omit<AttachOptions<TContext>, "contextFactory" | "prompts" | "telemetry">;

Defined in: packages/core/src/server/startServer.ts:127

Extra attach options (debug, tracing, zeroTrust, etc.).

contextFactory()? ​

ts
readonly optional contextFactory: (extra) => TContext | Promise<TContext>;

Defined in: packages/core/src/server/startServer.ts:50

Factory to create per-request context.

Parameters ​

ParameterType
extraunknown

Returns ​

TContext | Promise<TContext>

cors? ​

ts
readonly optional cors: CorsConfig;

Defined in: packages/core/src/server/startServer.ts:124

CORS configuration for the HTTP transport. When provided, sets Access-Control-Allow-* headers on all /mcp responses and handles OPTIONS preflight requests automatically.

Default: no CORS headers (most restrictive).

Example ​

ts
startServer({
    transport: 'http',
    cors: { origin: 'https://app.example.com' },
});

credentials? ​

ts
readonly optional credentials: CredentialsMap;

Defined in: packages/core/src/server/startServer.ts:182

Credential declarations for marketplace-published servers (BYOC).

Each key becomes an environment variable name injected at runtime via globalThis.__vinkius_secrets. The marketplace reads this map and prompts the buyer to configure credentials before server activation.

Use requireCredential(key) inside tool handlers to read values.

Example ​

ts
import { defineCredentials } from '@vurb/core';

export const credentials = defineCredentials({
  API_KEY: { label: 'API Key', description: 'Your key', type: 'api_key', required: true, sensitive: true },
});

await startServer({ name: 'my-server', registry, credentials });

maxBodyBytes? ​

ts
readonly optional maxBodyBytes: number;

Defined in: packages/core/src/server/startServer.ts:75

Maximum request body size in bytes for the HTTP transport. Requests exceeding this limit are rejected with HTTP 413.

Default ​

ts
4_194_304 (4MB)

maxSessions? ​

ts
readonly optional maxSessions: number;

Defined in: packages/core/src/server/startServer.ts:107

Maximum number of concurrent sessions for the HTTP transport. New session initialization requests are rejected with HTTP 503 when this limit is reached.

Default ​

ts
1000

name ​

ts
readonly name: string;

Defined in: packages/core/src/server/startServer.ts:38

Server display name (shown in MCP clients and Inspector).

port? ​

ts
readonly optional port: number;

Defined in: packages/core/src/server/startServer.ts:67

Port for the HTTP server (only used when transport: 'http').

Default ​

ts
3001

prompts? ​

ts
readonly optional prompts: PromptRegistry<TContext>;

Defined in: packages/core/src/server/startServer.ts:47

Optional prompt registry.

rateLimitPerMinute? ​

ts
readonly optional rateLimitPerMinute: number;

Defined in: packages/core/src/server/startServer.ts:98

Maximum number of requests per session per minute for the HTTP transport. Requests exceeding this limit are rejected with HTTP 429.

Default ​

ts
600

registry ​

ts
readonly registry: ServerRegistry<TContext>;

Defined in: packages/core/src/server/startServer.ts:44

The tool registry to expose.

sessionReapIntervalMs? ​

ts
readonly optional sessionReapIntervalMs: number;

Defined in: packages/core/src/server/startServer.ts:90

How often (in ms) the session reaper runs to clean up stale sessions.

Default ​

ts
300_000 (5 minutes)

sessionTtlMs? ​

ts
readonly optional sessionTtlMs: number;

Defined in: packages/core/src/server/startServer.ts:83

Session TTL in milliseconds for the HTTP transport. Sessions with no activity beyond this duration are reaped automatically.

Default ​

ts
1_800_000 (30 minutes)

state? ​

ts
readonly optional state: Record<string, unknown>;

Defined in: packages/core/src/server/startServer.ts:160

Mutable state that survives V8 Isolate hibernation cycles.

When running on Vinkius Cloud Edge, this object is serialized to disk before the isolate is disposed (hibernated) and restored transparently when the next tool call arrives. The developer never notices the cycle.

Requirements:

  • Must be JSON-serializable (no functions, Map, Set, or circular refs)
  • Keep the state small (< 1MB) for sub-millisecond serialization
  • Use for counters, session data, caches — not for large datasets

When running locally (stdio/http transport), this option is ignored — the server stays in memory and state is naturally preserved.

Example ​

typescript
const myState = { requestCount: 0, sessions: {} };

// Tools use the state via closure capture:
const tool = defineTool({
    name: 'greet',
    handler: () => {
        myState.requestCount++;
        return { content: [{ type: 'text', text: `Request #${myState.requestCount}` }] };
    },
});

await startServer({ name: 'my-server', registry, state: myState });

telemetry? ​

ts
readonly optional telemetry: boolean;

Defined in: packages/core/src/server/startServer.ts:53

Enable Inspector TUI telemetry (default: true).

transport? ​

ts
readonly optional transport: ServerTransport;

Defined in: packages/core/src/server/startServer.ts:61

Transport layer: 'stdio' (default) or 'http' (Streamable HTTP).

  • stdio — connects via stdin/stdout (for Cursor, Claude Desktop)
  • http — starts an HTTP server with session management on /mcp

version? ​

ts
readonly optional version: string;

Defined in: packages/core/src/server/startServer.ts:41

Server version string (e.g. '1.0.0').