MCP Error Codes

Standardized error codes for MCP (Model Context Protocol) servers in PHP.

Installation

composer require code-wheel/mcp-error-codes

Usage

use CodeWheel\McpErrorCodes\ErrorCode;

// Use constants for consistent error responses
$response = [
    'success' => false,
    'code' => ErrorCode::NOT_FOUND,
    'error' => 'User not found',
];

// Check error category
$category = ErrorCode::getCategory(ErrorCode::NOT_FOUND); // 'resource'

// Check if client should retry
$shouldRetry = ErrorCode::isRecoverable(ErrorCode::RATE_LIMIT_EXCEEDED); // true

// Map to HTTP status
$httpStatus = ErrorCode::getHttpStatus(ErrorCode::NOT_FOUND); // 404

// Validate error codes
if (ErrorCode::isValid($code)) {
    // Known error code
}

Error Categories

Category	Codes	Description
access	INSUFFICIENT_SCOPE, ADMIN_REQUIRED, ACCESS_DENIED, RATE_LIMIT_EXCEEDED	Permission/auth errors
resource	NOT_FOUND, ALREADY_EXISTS, ENTITY_IN_USE, ENTITY_PROTECTED	Entity/resource state errors
validation	VALIDATION_ERROR, INVALID_NAME, INVALID_FILE_TYPE, PAYLOAD_TOO_LARGE, MISSING_REQUIRED	Input validation errors
operation	INTERNAL_ERROR, OPERATION_FAILED, TIMEOUT, CONFIRMATION_REQUIRED	Operation execution errors
domain	TEMPLATE_NOT_FOUND, CRON_FAILED, MIGRATION_FAILED, etc.	Domain-specific errors

All Error Codes

Access Control

• INSUFFICIENT_SCOPE - Write operations not allowed
• ADMIN_REQUIRED - Operation requires admin scope
• ACCESS_DENIED - Generic access denied
• RATE_LIMIT_EXCEEDED - Rate limit exceeded

Resource

• NOT_FOUND - Entity/resource not found
• ALREADY_EXISTS - Duplicate entity
• ENTITY_IN_USE - Cannot delete/modify entity in use
• ENTITY_PROTECTED - Protected entity

Validation

• VALIDATION_ERROR - Input validation failed
• INVALID_NAME - Invalid machine name format
• INVALID_FILE_TYPE - Invalid file type
• PAYLOAD_TOO_LARGE - Size limit exceeded
• MISSING_REQUIRED - Required parameter missing

Operation

• INTERNAL_ERROR - Internal server error
• OPERATION_FAILED - Operation failed
• TIMEOUT - Operation timed out
• CONFIRMATION_REQUIRED - Confirmation needed

Domain-Specific

• TEMPLATE_NOT_FOUND - Template not found
• CRON_FAILED - Cron job failed
• MIGRATION_FAILED - Migration failed
• RECIPE_FAILED - Recipe application failed
• CONFIG_ERROR - Configuration error
• MEDIA_ERROR - Media processing failed
• SERVICE_UNAVAILABLE - External service unavailable

HTTP Status Mapping

Error Code	HTTP Status
ACCESS_DENIED, INSUFFICIENT_SCOPE, ADMIN_REQUIRED	403
RATE_LIMIT_EXCEEDED	429
NOT_FOUND, TEMPLATE_NOT_FOUND	404
ALREADY_EXISTS, ENTITY_IN_USE, ENTITY_PROTECTED	409
VALIDATION_ERROR, INVALID_NAME, INVALID_FILE_TYPE, MISSING_REQUIRED	400
PAYLOAD_TOO_LARGE	413
TIMEOUT	408
SERVICE_UNAVAILABLE	503
All others	500

Recoverable Errors

These errors may resolve on retry:

• RATE_LIMIT_EXCEEDED - Wait and retry
• TIMEOUT - Retry with backoff
• SERVICE_UNAVAILABLE - External service may recover
• INTERNAL_ERROR - Transient server issue

License

MIT