Delphi MCP Server

A Model Context Protocol (MCP) server implementation in Delphi, designed to integrate with Claude Code, Codex, and other MCP-compatible clients for AI-powered Delphi development workflows.

Table of Contents

• Features
• Requirements
• Installation
• Transport Modes
• Using as a Library
• Integration with Claude Code
• Integration with Codex
• Testing with MCP Inspector
• Available Example Tools
• Available Example Resources
• Configuration
• License
• Contributing
• About GDK Software
• Support

Features

• Full MCP Protocol Support: Implements MCP specification 2025-06-18 with Streamable HTTP and SSE
• Dual Transport Support: HTTP (Streamable HTTP with SSE) and STDIO (stdin/stdout)
• Dual Response Mode: Supports both JSON-RPC and Server-Sent Events in the same server
• Tool System: Extensible tool system with RTTI-based discovery and execution
• Resource Management: Modular resource system supporting various content types
• Security: Built-in security features including CORS configuration
• High Performance: Native implementation using Indy HTTP Server with keep-alive support
• Optional Parameters: Support for optional tool parameters using custom attributes
• Cross-Platform: Supports Windows (Win32/Win64) and Linux (x64)

Requirements

• Delphi 12 Athens or later
• Windows (Win32/Win64) or Linux (x64)
• No external dependencies (all required libraries included)

Installation

For Standalone Usage

1. Clone the repository:

git clone https://github.com/GDKsoftware/delphi-mcp-server.git
cd delphi-mcp-server

2. Build the project:

Windows Build

build.bat

Or specify configuration and platform:

build.bat Debug Win32
build.bat Release Win64

The script picks up the highest TaurusTLS version installed in the CatalogRepository of the Studio release that DELPHI_PATH points at. To build against a copy somewhere else, set TAURUS_PATH to its Source directory first:

set TAURUS_PATH=C:\path\to\TaurusTLS\Source
build.bat Release Win64

Linux Build

Prerequisites:

• Delphi Enterprise with Linux platform support
• PAServer running on Linux target machine
• Linux SDK configured in RAD Studio

From the batch file:

build.bat Release Linux64

Or from RAD Studio IDE:

1. Open MCPServer.dproj
2. Select Linux64 platform
3. Build

Transport Modes

The server supports two transport modes:

HTTP Transport (Default)

Start the server without arguments for HTTP transport with Server-Sent Events (SSE):

Win32\Debug\MCPServer.exe

The server will listen on http://localhost:3000/mcp by default (configurable via settings.ini).

Use HTTP transport for:

• Claude Code (SSE support)
• MCP Inspector
• Web-based clients
• Remote connections

STDIO Transport

Start the server with --stdio flag for stdin/stdout communication:

Win32\Debug\MCPServer.exe --stdio

The server will:

• Read JSON-RPC requests from stdin (one per line)
• Write JSON-RPC responses to stdout (one per line)
• Log diagnostic messages to stderr

Use STDIO transport for:

• Codex (OpenAI)
• Local MCP clients that use process spawning
• Automated testing and scripting

Supported flag variants: --stdio, -stdio, /stdio

Using as a Library

The Delphi MCP Server is designed to be used both as a standalone application and as a library for your own MCP server implementations. This section covers how to integrate it into your existing Delphi projects.

Project Setup for Library Usage

Option 1: Git Submodule (Recommended)

# Add MCPServer as a submodule to your project
git submodule add https://github.com/GDKsoftware/delphi-mcp-server.git lib/mcpserver
git submodule update --init --recursive

Option 2: Direct Source Inclusion

Copy the src folder from MCPServer into your project and add the units to your uses clauses.

Delphi Project Configuration

1. Search Paths: Add the MCPServer source directories to your project search path:

   • lib\mcpserver\src\Core
   • lib\mcpserver\src\Managers
   • lib\mcpserver\src\Protocol
   • lib\mcpserver\src\Server
   • lib\mcpserver\src\Tools
   • lib\mcpserver\src\Resources

2. Required Units: Include these core units in your project:

   MCPServer.Types,
   MCPServer.Settings,
   MCPServer.Registration,
   MCPServer.ManagerRegistry,
   MCPServer.IdHTTPServer,      // For HTTP transport
   MCPServer.StdioTransport,    // For STDIO transport
   MCPServer.JsonRpcProcessor   // Shared JSON-RPC processing
   

Library Integration

Once you have the project setup complete, the simplest way to add MCP capabilities to your application:

program YourMCPServer;

{$APPTYPE CONSOLE}

uses
  System.SysUtils,
  MCPServer.Types in 'lib\mcpserver\src\Protocol\MCPServer.Types.pas',
  MCPServer.IdHTTPServer in 'lib\mcpserver\src\Server\MCPServer.IdHTTPServer.pas',
  MCPServer.Settings in 'lib\mcpserver\src\Core\MCPServer.Settings.pas',
  MCPServer.ManagerRegistry in 'lib\mcpserver\src\Core\MCPServer.ManagerRegistry.pas',
  MCPServer.CoreManager in 'lib\mcpserver\src\Managers\MCPServer.CoreManager.pas',
  MCPServer.ToolsManager in 'lib\mcpserver\src\Managers\MCPServer.ToolsManager.pas',
  MCPServer.ResourcesManager in 'lib\mcpserver\src\Managers\MCPServer.ResourcesManager.pas';

var
  Server: TMCPIdHTTPServer;
  Settings: TMCPSettings;
  ManagerRegistry: IMCPManagerRegistry;
  
begin
  Settings := TMCPSettings.Create;
  try
    ManagerRegistry := TMCPManagerRegistry.Create;
    ManagerRegistry.RegisterManager(TMCPCoreManager.Create(Settings));
    ManagerRegistry.RegisterManager(TMCPToolsManager.Create);
    ManagerRegistry.RegisterManager(TMCPResourcesManager.Create);
    
    Server := TMCPIdHTTPServer.Create(nil);
    try
      Server.Settings := Settings;
      Server.ManagerRegistry := ManagerRegistry;
      Server.Start;
      
      Writeln('MCP Server running on port ', Settings.Port);
      Readln; // Keep running
      
      Server.Stop;
    finally
      Server.Free;
    end;
  finally
    Settings.Free;
  end;
end.

Creating Custom Tools

unit YourProject.Tool.Custom;

interface

uses
  MCPServer.Tool.Base,
  MCPServer.Types,
  MCPServer.Registration;

type
  TCustomToolParams = class
  private
    FInput: string;
    FCount: Integer;
  public
    [SchemaDescription('Text input to process')]
    property Input: string read FInput write FInput;
    
    [Optional]
    [SchemaDescription('Number of times to repeat (default: 1)')]
    property Count: Integer read FCount write FCount;
  end;

  TCustomTool = class(TMCPToolBase<TCustomToolParams>)
  protected
    function ExecuteWithParams(const AParams: TCustomToolParams): string; override;
  public
    constructor Create; override;
  end;

implementation

constructor TCustomTool.Create;
begin
  inherited;
  FName := 'custom_tool';
  FDescription := 'A custom tool that processes input';
end;

function TCustomTool.ExecuteWithParams(const AParams: TCustomToolParams): string;
var
  I: Integer;
  Output: string;
begin
  Output := '';
  for I := 1 to AParams.Count do
    Output := Output + AParams.Input + #13#10;
  Result := 'Processed: ' + Output;
end;

initialization
  TMCPRegistry.RegisterTool('custom_tool',
    function: IMCPTool
    begin
      Result := TCustomTool.Create;
    end
  );

end.

Creating Custom Resources

unit YourProject.Resource.Custom;

interface

uses
  System.SysUtils,
  MCPServer.Resource.Base,
  MCPServer.Registration;

type
  TCustomData = class
  private
    FMessage: string;
    FTimestamp: TDateTime;
  public
    property Message: string read FMessage write FMessage;
    property Timestamp: TDateTime read FTimestamp write FTimestamp;
  end;

  TCustomResource = class(TMCPResourceBase<TCustomData>)
  protected
    function GetResourceData: TCustomData; override;
  public
    constructor Create; override;
  end;

implementation

constructor TCustomResource.Create;
begin
  inherited;
  FURI := 'custom://data';
  FName := 'Custom Data';
  FDescription := 'Custom resource data';
  FMimeType := 'application/json';
end;

function TCustomResource.GetResourceData: TCustomData;
begin
  Result := TCustomData.Create;
  Result.Message := 'Hello from custom resource';
  Result.Timestamp := Now;
end;

initialization
  TMCPRegistry.RegisterResource('custom://data',
    function: IMCPResource
    begin
      Result := TCustomResource.Create;
    end
  );

end.

Integration with Claude Code

Configure using the Streamable HTTP transport:

# Basic configuration
claude mcp add --transport http delphi-mcp-server http://localhost:3000/mcp

# With authentication (if configured)
claude mcp add --transport http delphi-mcp-server http://localhost:3000/mcp --header "Authorization: Bearer your-token"

Make sure the server is running before connecting Claude Code.

Integration with Codex

Configure Codex to use the STDIO transport. Edit your Codex configuration file (~/.codex/config.toml):

[mcp_servers.delphi-mcp-server]
command = 'C:\path\to\MCPServer.exe'
args = ["--stdio"]

Or on Linux/macOS:

[mcp_servers.delphi-mcp-server]
command = '/path/to/MCPServer'
args = ["--stdio"]

Important: The server must be compiled and the executable path must be absolute.

After configuration:

1. Restart Codex
2. Use /mcp command to verify the server is connected
3. Available tools will appear in the Codex interface

HTTPS/SSL Configuration

The server supports HTTPS connections when configured with SSL certificates:

1. Generate SSL Certificates:

   # Generate self-signed certificates (for development)
   generate-ssl-cert.bat
   

   This creates certificates in the certs directory.

2. Configure SSL in settings.ini:

   [SSL]
   Enabled=1  ; Use 1 (true) or 0 (false)
   CertFile=C:\path\to\server.crt
   KeyFile=C:\path\to\server.key
   RootCertFile=C:\path\to\ca.crt  ; Optional
   

3. Start the server: The server will automatically use HTTPS when SSL is enabled.

Note: For production, use certificates from a trusted Certificate Authority (CA) instead of self-signed certificates.

Testing with MCP Inspector

The easiest way to test and debug your MCP server is using the official MCP Inspector:

1. Start the server:

   # Build and run the server
   build.bat
   Win32\Debug\MCPServer.exe
   

2. Run MCP Inspector:

   # Install and run the MCP Inspector
   npx @modelcontextprotocol/inspector
   

3. Connect to your server:

   • Transport: HTTP
   • URL: http://localhost:3000/mcp
   • Click Connect

4. Test functionality:

   • Browse available tools and resources
   • Execute tools like echo, get_time, calculate
   • View resources like project://info, server://status
   • Monitor request/response JSON-RPC messages

The Inspector provides a web interface to interact with your MCP server, making it perfect for development and debugging.

Available Example tools

• echo: Echo a message back to the user
• get_time: Get the current server time
• list_files: List files in a directory
• calculate: Perform basic arithmetic calculations

Available Example resources

The server provides four essential resources accessible via URIs:

• project://info - Project information (JSON metadata with collections)
• project://readme - This README file (markdown content)
• logs://recent - Recent log entries from all categories (with thread safety)
• server://status - Current server status and health information

Configuration

The server supports configuration through settings.ini files. A default settings.ini.example is provided in the repository.

SSL/TLS Configuration

The Delphi MCP Server supports two SSL/TLS implementations:

1. Standard Indy SSL - Uses OpenSSL 1.0.2 (default if TaurusTLS not available)
2. TaurusTLS - Uses OpenSSL 3.x or 4.x with modern cipher support (recommended)

Installing TaurusTLS

TaurusTLS provides OpenSSL 3.x and 4.x support with modern ECDHE cipher suites required by services like Cloudflare.

Via a package manager (easiest):

• GetIt (RAD Studio): Tools > GetIt Package Manager, search for "TaurusTLS", click Install
• DPM: dpm install TaurusTLS_Developers.TaurusTLS
• TMS Smart Setup: tms install taurustls_developers.taurustls

Manual Installation:

1. Clone from https://github.com/TaurusTLS-Developers/TaurusTLS
2. Open TaurusTLS\Packages\d12\TaurusAll.groupproj
3. Compile TaurusTLS_RT
4. Compile and install TaurusTLS_DT

All installation options are documented at https://taurustls.org/download.xhtml

Switching Between SSL Implementations

Edit src\Server\MCPServer.IdHTTPServer.pas:

// To use TaurusTLS (OpenSSL 3.x/4.x):
{$DEFINE USE_TAURUS_TLS}  // Keep this line uncommented

// To use Standard Indy SSL (OpenSSL 1.0.2):
// {$DEFINE USE_TAURUS_TLS}  // Comment out this line

OpenSSL Requirements

For TaurusTLS:

TaurusTLS runs on OpenSSL 3.x and 4.x. Pre-compiled binaries for every supported platform, including Windows on ARM64, are published at https://github.com/TaurusTLS-Developers/OpenSSL-Distribution/releases. Full deployment instructions: https://taurustls.org/deployapps.xhtml

OpenSSL 4.x requires TaurusTLS 1.0.5.42 or newer. Earlier releases only look for the 3.x, 1.1 and 1.0 library names, so a build linked against them fails at startup with ETaurusTLSCouldNotLoadSSLLibrary: Could not load SSL library when only 4.x libraries are present. Check DefaultLibVersions in TaurusTLSConsts.pas if you are unsure which version you have.

Windows (dynamic linking):

Ship the OpenSSL DLLs and LICENSE.txt alongside your executable:

Target	OpenSSL 3.x	OpenSSL 4.x
Win32	libcrypto-3.dll, libssl-3.dll	libcrypto-4.dll, libssl-4.dll
Win64	libcrypto-3-x64.dll, libssl-3-x64.dll	libcrypto-4-x64.dll, libssl-4-x64.dll
Windows ARM64EC	libcrypto-3-arm64.dll, libssl-3-arm64.dll	libcrypto-4-arm64.dll, libssl-4-arm64.dll

Instead of copying DLLs by hand, the OpenSSL-Distribution releases also ship automated installers you can run yourself or chain from your own installer:

• InnoSetup installer (openssl-<version>-Windows-installer.exe) - one setup covering x86, x64 and ARM64EC, picking the matching runtime by CPU detection. Silent install:

  openssl-<version>-Windows-installer.exe /VERYSILENT /SUPPRESSMSGBOXES /NORESTART
  

• MSIX framework packages (openssl-<version>-Windows-x64.msix, -x86.msix, -arm64ec.msix) - reference them from your own AppxManifest.xml as a PackageDependency on TaurusTLS.OpenSSL.

Linux (dynamic linking):

• OpenSSL is usually installed by default; document the dependency for your end users
• Update if needed: sudo apt-get install libssl-dev (Debian/Ubuntu) or sudo yum install openssl-devel (RHEL/CentOS)
• To pin a specific version, redistribute the Linux package from the OpenSSL-Distribution releases

macOS, iOS and Android (static linking):

• OpenSSL is compiled into the application binary; build against the .a files in the lib\static folder of the platform archive (for example openssl-<version>-macOS-arm64.zip)
• Nothing to redistribute besides your application package and LICENSE.txt

For Standard Indy:

• Requires OpenSSL 1.0.2 DLLs (libeay32.dll, ssleay32.dll)
• Limited cipher support, not recommended for modern clients

Known Issues & Solutions

• Cloudflare Tunnel: Standard Indy SSL lacks ECDHE cipher support. Use TaurusTLS or run Cloudflare Tunnel with HTTP: cloudflared tunnel --url http://localhost:8080
• Self-Signed Certificates: Claude Desktop doesn't accept self-signed certificates. Use Cloudflare Tunnel or a valid certificate from a trusted CA
• "No shared cipher" error: Install and enable TaurusTLS for modern cipher support
• Could not load SSL library: no OpenSSL library TaurusTLS recognises was found. Either the libraries are not where the platform looks for them, or your TaurusTLS version predates 4.x support (see above)
• The wrong OpenSSL gets loaded: TaurusTLS asks the OS for the libraries by name, trying the version suffixes newest first, and takes the first hit anywhere on the platform's library search path. Another OpenSSL installation can therefore win over the one you shipped, and your application runs on a version you never tested. Set the OPENSSL_LIBRARY_PATH environment variable to an absolute directory to pin the choice; it applies on every platform

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

We welcome contributions! Here's how to help:

Reporting Issues

• Use GitHub Issues for bugs and feature requests
• Include Delphi version, platform, and reproduction steps

Pull Requests

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Follow existing code style (inline vars, named constants)
4. Test your changes
5. Submit a pull request

Development Setup

• Requires Delphi 12+
• Open MCPServer.dproj or build with build.bat
• Test with npx @modelcontextprotocol/inspector or Claude Code or similar

About GDK Software

GDK Software is a Delphi specialist: we build, upgrade and maintain Delphi applications worldwide, and offer Delphi and AI consultancy and AI training.

Support

• Create an issue on GitHub
• Visit our website at www.gdksoftware.com

Commercial Support

This library is MIT licensed and free to use. For companies that depend on it commercially we offer support and maintenance agreements with guaranteed response times, and sponsored development of features you need, such as upcoming MCP specification revisions. Contact us at gdksoftware.com/contact-us or open an issue to get in touch.