andrea-magni/mars/mars-mcp-server

Build an MCP server with MARS-Curiosity

MARS ships native MCP support (units MARS.MCP.* in Source/): derive a resource from TMCPResource, mark methods with [MCPTool], and any MARS server becomes an MCP server speaking the Streamable HTTP transport (single endpoint, JSON-RPC 2.0 over POST). Tool list and JSON Schema are generated from RTTI — no protocol code to write.

The complete working example is Demos/MCPServer in the MARS repository (public tools + FireDAC-backed authenticated tools + OAuth).

MCP servers are built on resources (TMCPResource), also in projects that define their REST endpoints as routes (MARS.Core.Routes, MARSTemplateRoutes): routes are an addition to resources, and an MCP resource lives next to them in the same application. Add it to the application's resources ('Server.Resources.*' mask) as shown below.

Minimal MCP server

unit Server.Resources.MCP;
 
interface
 
uses
  SysUtils, Classes
, MARS.Core.Attributes, MARS.Core.MediaType
, MARS.MCP.Resource, MARS.MCP.Attributes;
 
type
  TCalculationResult = record
    operation: string;
    value: Double;
  end;
 
  [Path('mcp')
  , MCPServerInfo('My MCP Server', '1.0.0'
    , 'Optional instructions the AI agent reads on connection.')]
  TMyMCPResource = class(TMCPResource)
  public
    [MCPTool('say_hello', 'Returns a friendly greeting for the given name')]
    function SayHello(
      [MCPParam('name', 'Name of the person to greet')] const AName: string): string;
 
    [MCPTool('add_numbers', 'Adds two numbers and returns a structured result')]
    function AddNumbers(
      [MCPParam('a', 'First operand')] const A: Double;
      [MCPParam('b', 'Second operand')] const B: Double): TCalculationResult;
  end;
 
implementation
 
uses
  MARS.Core.Registry;
 
function TMyMCPResource.SayHello(const AName: string): string;
begin
  Result := 'Hello, ' + AName + '!';
end;
 
function TMyMCPResource.AddNumbers(const A, B: Double): TCalculationResult;
begin
  Result.operation := 'add';
  Result.value := A + B;
end;
 
initialization
  MARSRegister([TMyMCPResource]);
 
end.

This is a regular MARS resource: register the unit mask in Server.Ignition.pas as usual (AddApplication('DefaultApp', '/default', ['Server.Resources.*'])). The MCP endpoint is the composed URL, e.g. http://localhost:8080/rest/default/mcp. Everything the mars-development skill says about resources, [Context] injection and configuration applies here too.

A complete starting unit is available in assets/Server.Resources.MCP.pas.template.

What the attributes do

Tool results: a string becomes a text content block; records (and arrays, numbers...) are serialized with the MARS JSON serializer and records also become structuredContent. Exceptions raised inside a tool are reported as tool execution errors (isError: true), not protocol errors. TDataSet results need TMCPDataResource — see references/database-tools.md.

Parameter/field types map to JSON Schema automatically: strings → string, integers → integer, floats → number, Boolean → boolean, enums → string + enum values, TDateTime → string/date-time, TDate → string/date ("2026-10-19"), dynamic arrays → array, records → nested object. Parameters are listed as required, except those marked [MCPDefault('<JSON literal>')]: they are left out of required, the schema advertises the value as default, and a missing or null argument is bound to it ([MCPDefault('true')], ('7'), ('"value_date"'), ('""'), ('[]') — the literal is converted like any argument).

Protocol facts worth knowing

• Supported JSON-RPC methods: initialize (protocol versions 2025-06-18, 2025-03-26, 2024-11-05), ping, tools/list, tools/call, resources/list, resources/templates/list, resources/read, prompts/list, prompts/get. Notifications answer 202 with no body; GET/DELETE answer 405 (stateless server, allowed by spec). The resources/prompts capabilities are advertised only when the class declares any. Extend TMCPDispatcher.DispatchRequest for additional methods.
• Tool discovery is cached per resource class (thread-safe, RTTI scanned once). The authorization filter is evaluated per request, so caching never leaks role-protected tools.
• The dispatcher class is pluggable: override GetDispatcherClass on the resource (that is how TMCPDataResource adds dataset support).
• A local server on stdio, without HTTP: TMCPStdioServer.Serve(TMyTools.Create, 'name', '1.0.0') in a console program (MARS.MCP.Stdio; JSON-RPC a line each on stdin/stdout, UTF-8; log only to stderr), registered with claude mcp add name -- path\to\exe.

When to read the references

• Any authentication requirement — Bearer tokens, roles, hiding tools per user, OAuth login window for Claude/ChatGPT/Open WebUI: read references/authorization.md first, it also lists client-specific pitfalls that look like server bugs.
• Tools that query a database (FireDAC, TFDQuery, TMARSFireDAC, or Devart UniDAC/MyDAC/IBDAC with TMARSUniDAC/TMARSMyDAC/TMARSIBDAC): read references/database-tools.md — dataset ownership rules matter.
• MCP resources or prompts (attachable content like DB schemas, URI templates, reusable prompt templates): read references/resources-prompts.md.
• Interactive UIs / MCP Apps (a chart, form or dashboard rendered by Claude or another host next to a tool result, ui:// resources): read references/mcp-apps.md.

Verify the server

With curl (initialize / list / call):

curl -X POST http://localhost:8080/rest/default/mcp -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
 
curl -X POST http://localhost:8080/rest/default/mcp -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"add_numbers","arguments":{"a":2,"b":3}}}'

With the official MCP Inspector (needs Node.js), which performs a real client handshake:

npx @modelcontextprotocol/inspector --cli http://localhost:8080/rest/default/mcp --transport http --method tools/list

Connect real clients: claude mcp add --transport http my-server http://localhost:8080/rest/default/mcp, or in Open WebUI add an External Tools connection of type MCP (Streamable HTTP) (requires Open WebUI ≥ 0.6.31). Remember: from another machine/container, use the server's LAN IP, not localhost.

Troubleshooting quick table