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
• Protocol Versions and Dual-Era Behaviour
• Using as a Library
• Integration with Claude Code
• Integration with Codex
• Testing with MCP Inspector
• Available Example Tools
• Available Example Prompts
• Available Example Resources
• Configuration
  • Authentication
  • Network and Security
• License
• Contributing
• About GDK Software
• Support
• Commercial Support

Features

• Dual-era MCP: Serves MCP 2026-07-28 (per-request _meta, server/discover) and the initialize-based revisions 2025-06-18 and 2025-11-25 on the same endpoint and the same stdio process; see Protocol versions
• 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: Origin and Host validation against DNS rebinding on every request, loopback binding by default, CORS headers for browser clients, request size and nesting limits, opt-in bearer authentication with OAuth 2.1 resource-server discovery
• Multi round-trip requests, streaming and subscriptions: InputRequiredResult with signed requestState, progress and log notifications on the response stream, subscriptions/listen for change notifications
• Native HTTP stack: Indy HTTP server with keep-alive, no external runtime
• Optional Parameters: Support for optional tool parameters using custom attributes
• Cross-Platform: Supports Windows (Win32/Win64) and Linux (x64)

Requirements

• Delphi 11 Alexandria or later. The source uses no language feature beyond inline variables (10.3) and no RTL unit newer than Delphi 11; development happens on Delphi 12 Athens, which is what the default project files target.
• Windows (Win32/Win64) or Linux (x64)
• No external dependencies (all required libraries included)

Building with Delphi 11 Alexandria

build.bat and build-tests.bat compile the .dpr directly, so only DELPHI_PATH needs to point at your installation:

set DELPHI_PATH=C:\Program Files (x86)\Embarcadero\Studio\22.0
build.bat

For the IDE and for the Linux64 build, open src/MCPServer.D11.dproj (tests: tests/MCPServerTests.D11.dproj) instead of the Athens project files. They carry the same units and settings, write their output to a separate D11 subdirectory, and exist because Alexandria will not load a ProjectVersion 20.3 project file.

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 messages from stdin, UTF-8, one per line, no byte-order mark
• Write JSON-RPC messages to stdout the same way
• Log diagnostic messages to stderr, never to stdout
• Answer notifications/cancelled by stopping the named request; it gets no response
• Send notifications/progress for a request that carries _meta.progressToken, before its response
• Exit within [Server] MaxConcurrentRequests worker threads' drain time (2 seconds by default) once stdin closes

Use STDIO transport for:

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

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

By default requests are answered one at a time, in the order they arrive. [Server] MaxConcurrentRequests in settings.ini raises the number of worker threads for a client that issues concurrent requests over the same process; a stdio server never writes settings.ini on its own, so this and the other [Server] limits still need explicit configuration when they should differ from the defaults.

A tool sees the request it is answering through TMCPRequestContext.Current: CheckCancelled raises once the client cancels, ReportProgress sends a notifications/progress when the request carries a progress token, and Log sends a notifications/message when the request carries _meta.io.modelcontextprotocol/logLevel and the message's level is at or above it. See test_tool_with_progress and test_logging_tool in MCPServer.Tool.ContentSamples for worked examples.

Over HTTP the same notifications reach the client on the response: when the request accepts text/event-stream and a tool sends one, the response turns into an SSE stream (chunked, X-Accel-Buffering: no) that carries the notifications first and the JSON-RPC response as its last event. A request that sends none is answered as before. A client that closes the stream cancels the request: the server's next write to it fails and the tool sees IsCancelled. That is the HTTP cancellation. A notifications/cancelled naming the same request is answered 202 and dropped, because the tracker a request consults is its own response stream and a notification always arrives on a connection of its own; only over stdio, where every message shares one channel, does the notification stop a running request.

Change notifications (subscriptions/listen)

A modern client that wants to hear about changes opens a long-lived subscriptions/listen request with a notifications filter (toolsListChanged, promptsListChanged, resourcesListChanged, resourceSubscriptions: a list of URIs). TMCPSubscriptionsManager (MCPServer.SubscriptionsManager) answers with notifications/subscriptions/acknowledged carrying the honoured filter and keeps the stream open: over HTTP as an SSE response with a keep-alive comment every 15 seconds, over stdio on a thread of its own so the worker threads stay free. Every message on the subscription carries _meta.io.modelcontextprotocol/subscriptionId, the JSON-RPC id of the subscriptions/listen request. Closing the SSE stream, or sending notifications/cancelled for that id over stdio, ends the subscription; when the server stops (or stdin closes) it answers the request with a completion result first.

Notifications are delivered synchronously on the thread that causes the change, so a subscriber that stops reading can hold up that thread until its socket buffer drains.

Assign the manager as ChangeNotifier of the tools, prompts and resources managers, as MCPServer.dpr does, and the tools, prompts and resources capabilities announce listChanged (and resources.subscribe) to modern clients. AddTool, RemoveTool, AddPrompt, RemovePrompt, AddResource, RemoveResource and AddResourceTemplate then notify the subscribed clients, and TMCPResourcesManager.ResourceUpdated(Uri) reports a changed resource to the clients that subscribed to that URI. Without a ChangeNotifier nothing is announced and nothing is sent.

Protocol Versions and Dual-Era Behaviour

The server decides per request which protocol era it is speaking; nothing is negotiated per connection and no session is minted.