Server Architecture

Deep dive into the IBM i MCP Server architecture, including the ‘Logic Throws, Handler Catches’ pattern, component interactions, and lifecycle management.

Server Architecture

The IBM i MCP Server follows a carefully designed architecture that ensures modularity, testability, and operational clarity through strict separation of concerns. This guide explores the core architectural patterns and component interactions.

The architecture is built around the “Logic Throws, Handler Catches” principle, which forms the foundation of our error-handling and control-flow strategy.

Core Architectural Principles

1. Logic Throws, Handler Catches

This immutable pattern ensures clean separation between business logic and transport handling:

Logic Layer (logic.ts)

Responsibilities:

• Execute pure business logic
• Remain stateless and self-contained
• Terminate by throwing structured McpError on failure
• Never contain try…catch blocks for response formatting

// Example from catFactFetcher/logic.ts
export async function catFactFetcherLogic(
  params: CatFactFetcherInput,
): Promise<CatFactFetcherResponse> {
  // Pure business logic execution
  if (params.message === "fail") {
    throw new McpError(
      BaseErrorCode.VALIDATION_ERROR,
      "Deliberate failure triggered",
      { toolName: "cat_fact_fetcher" }
    );
  }
  return processedResult;
}

2. Structured Request Context

Every operation maintains traceability through structured logging:

const context = requestContextService.createRequestContext({
  operation: "HandleToolRequest",
  toolName: TOOL_NAME,
  input: params,
});

Application Architecture Overview

Server Startup Sequence

The application follows a precise startup sequence ensuring all components are properly initialized:

Key Architectural Decision: The startup sequence registers ALL tools during initialization, not on-demand. This ensures consistent tool availability and enables proper error handling during startup rather than runtime failures.

Tool Execution Flow

Every tool follows the same execution pattern, ensuring consistency and reliability:

Component Architecture

Tool Development Structure

Each tool follows a mandated three-file structure that enforces the architectural patterns:

SQL Tools Architecture

IBM i-specific SQL tools use a YAML-driven approach for rapid development:

Error Handling Architecture

The error handling system provides comprehensive coverage while maintaining system stability:

Authentication & Security Architecture

The server supports multiple authentication modes with integrated IBM i security:

Transport Layer Architecture

The server supports both development and production transport modes:

STDIO Transport

Use Cases:

• CLI tools and MCP Inspector
• Direct process communication
• Development and testing

Observability & Monitoring

The architecture includes comprehensive observability features:

Best Practices & Patterns

Tool Development Guidelines

• Logic Purity: Keep business logic functions pure and stateless
• Error Throwing: Always throw McpError for failures in logic layer
• Handler Wrapping: Every logic call must be wrapped in try…catch in handlers
• Context Propagation: Pass RequestContext through the entire call stack
• Schema Validation: Define comprehensive Zod schemas for inputs and outputs

YAML SQL Tool Patterns

• Parameter Security: Use parameter binding to prevent SQL injection
• Authority Checking: Include appropriate IBM i authority requirements
• Result Limiting: Always include row limits for large result sets
• Audit Logging: Mark sensitive operations with security.audit: true
• Performance Consideration: Design queries for production system impact

Error Handling Standards

• Structured Errors: Always use McpError with appropriate error codes
• Context Inclusion: Include relevant context in error details
• No Silent Failures: Every error must be logged and handled
• Graceful Degradation: Provide meaningful fallback behaviors
• Client Communication: Return user-friendly error messages

Security Implementation

• Input Validation: Validate all inputs with Zod schemas
• Authorization Checks: Verify scope requirements for sensitive operations
• IBM i Integration: Leverage IBM i’s built-in security model
• Audit Trails: Maintain comprehensive audit logs
• Credential Management: Use environment variables for sensitive data

Integration Points

The architecture provides multiple integration points for extending functionality:

Custom SQL Tools

Extend functionality with YAML SQL configurations for IBM i database operations

Agent Development

Build AI agents that understand the server architecture and IBM i concepts

Authentication Providers

Implement custom authentication modes and IBM i security integration

Production Deployment

Connect observability data to enterprise monitoring and alerting systems

For complete configuration details including environment variables for each architectural component, see the Configuration Reference.

Architectural Philosophy: The “Logic Throws, Handler Catches” pattern ensures that business logic remains testable and pure, while handlers manage the complexity of transport protocols and error formatting. This separation enables reliable unit testing and makes the system easier to maintain and extend.

This architecture has been battle-tested in enterprise IBM i environments and follows industry best practices for production MCP server deployment. The modular design ensures that each component can be developed, tested, and maintained independently while working together as a cohesive system.