Skip to main content
When skills are exposed over HTTP (via skillsConfig.enabled), FrontMCP supports four authentication modes to protect skill endpoints.

​
Auth Modes

ModeHeaderValidationUse Case
inherit (default)Same as parent serverSame as parent serverReuse the server’s primary auth
publicNoneNoneDevelopment, internal networks
api-keyX-API-Key or Authorization: ApiKey <key>Timing-safe equalityMachine-to-machine, server-to-server
bearerAuthorization: Bearer <jwt>JWT signature via JWKSUser-scoped access, IdP integration

​
Configuration

​
Public Mode

Disable authentication on skill endpoints regardless of the parent server’s auth. 
@FrontMcp({
  skillsConfig: {
    enabled: true,
    auth: 'public',
  },
})
class Server {}

​
API Key Mode

@FrontMcp({
  skillsConfig: {
    enabled: true,
    auth: 'api-key',
    apiKeys: [
      process.env.SKILL_API_KEY_1,
      process.env.SKILL_API_KEY_2,
    ],
  },
})
class Server {}
Clients authenticate with either header format: 
X-API-Key: sk-your-api-key

Authorization: ApiKey sk-your-api-key
API key comparison uses timing-safe equality to prevent timing attacks. All configured keys are checked even after a match is found to maintain constant-time behavior.

​
JWT Bearer Mode

@FrontMcp({
  skillsConfig: {
    enabled: true,
    auth: 'bearer',
    jwt: {
      issuer: 'https://auth.example.com',
      audience: 'skills-api',           // Optional audience claim validation
    },
  },
})
class Server {}
JWT tokens are validated against the issuer’s JWKS endpoint (auto-discovered from {issuer}/.well-known/jwks.json).

​
Validation Result

The validator returns a structured result: 
interface SkillHttpAuthResult {
  authorized: boolean;
  error?: string;       // Human-readable error message
  statusCode?: number;  // HTTP status code (401, 403)
}

​
Factory Function

Use createSkillHttpAuthValidator() to create a validator from skill config: 
import { createSkillHttpAuthValidator } from '@frontmcp/sdk';

const validator = createSkillHttpAuthValidator(skillsConfig, logger);
// Returns null if no validation needed (public mode)

if (validator) {
  const result = await validator.validate({ headers: request.headers });
  if (!result.authorized) {
    return new Response(result.error, { status: result.statusCode });
  }
}

​
Tool Authorization Guard

When a skill session is active, the Tool Authorization Guard enforces which tools the skill is allowed to call. This prevents skill sessions from accessing tools outside their declared allowlist.

​
Policy Modes

ModeBehavior
strictTool must be in the skill’s allowlist. Denied tools throw ToolNotAllowedError.
approvalUnlisted tools trigger an approval flow. Throws ToolApprovalRequiredError until approved.
openAll tools are allowed (no enforcement).

​
Usage

import { ToolAuthorizationGuard } from '@frontmcp/sdk';

const guard = new ToolAuthorizationGuard(sessionManager, logger, {
  throwOnDenied: true,
  onApprovalRequired: async (toolName, skillId) => {
    // Custom approval logic (e.g., prompt user)
    return true; // or false to deny
  },
});

// Check if tool is allowed
const result = await guard.check('my_tool');

// Simple boolean check (never throws)
const allowed = await guard.isAllowed('my_tool');

// Manual approval/denial
guard.approveTool('my_tool');
guard.denyTool('dangerous_tool');

// Inspect current state
const mode = guard.getPolicyMode();      // 'strict' | 'approval' | 'open'
const tools = guard.getAllowlist();       // ['tool_a', 'tool_b']
const hasSkill = guard.hasActiveSkill(); // true/false

​
Error Types

​
ToolNotAllowedError

Thrown when a tool is not in the skill’s allowlist (strict mode).
PropertyTypeDescription
toolNamestringThe denied tool name
skillIdstring | undefinedActive skill session ID
reasonstringOne of: not_in_allowlist, denied, rate_limited, no_active_skill
allowedToolsstring[]List of allowed tool names
mcpErrorCodenumberMCP error code (INVALID_REQUEST)

​
ToolApprovalRequiredError

Thrown when a tool requires approval but has not been approved yet.
PropertyTypeDescription
toolNamestringThe tool requiring approval
skillIdstring | undefinedActive skill session ID
mcpErrorCodenumberMCP error code (INVALID_REQUEST)