Skip to content

RIDDL MCP Server

The MCP server now runs locally in riddlg

The RIDDL MCP tools ship inside the riddlg binary and run on your machine — riddlg mcp for stdio clients, or POST /mcp while riddlg serve is running. No account, no API key, and your models never leave your computer. The previously planned hosted server at mcp.ossuminc.com has been retired in favor of this local-first approach; the tool names and result shapes are unchanged, so existing clients keep working after you point them at the local server.

The RIDDL MCP Server is a Model Context Protocol (MCP) server that lets AI assistants reason about and generate RIDDL models. It provides validation, analysis, and suggestion tools that AI tools can use to help you build better domain models.

What is MCP?

The Model Context Protocol (MCP) is an open standard that allows AI assistants to connect to external tools and data sources. When you connect the RIDDL MCP Server to your AI assistant, it gains the ability to:

  • Validate RIDDL source for syntax and semantic errors
  • Analyze model completeness and suggest missing elements
  • Explain error messages and provide fix recommendations
  • Check whether a model is ready for simulation
  • Map natural-language domain descriptions to RIDDL structures
  • Expand built-in modeling patterns into RIDDL

Running the Server

First, install riddlg (see Installation):

brew install ossuminc/tap/riddlg

The MCP tools are then available over two transports — pick whichever your assistant supports:

Transport Command How the client connects
stdio riddlg mcp The client launches the process; configure command: riddlg, args: ["mcp"]
HTTP riddlg serve The client POSTs to http://127.0.0.1:8910/mcp (Streamable HTTP)

Neither transport needs an API key. The two expose the identical tool set; see Server API for the HTTP session and status-code details.

Available Tools

Thirteen tools are exposed; see MCP Tools for arguments and return shapes.

Tool Description
riddl_validate Validate RIDDL source; report parse/validation errors and warnings
riddl_outline Outline the named definitions (domains, contexts, entities, types)
check-completeness Find gaps: empty handlers, unresolved references, placeholders
suggest-next Suggest the next definitions to add, prioritized
map-domain-to-riddl Extract RIDDL structure from a natural-language description
validate-partial Validate an in-progress fragment, ignoring references to the unwritten rest
check-simulability Report whether (and why not) a model can be simulated
explain-error Explain a RIDDL diagnostic in plain language, with a likely fix
generate-test-cases Generate Given/When/Then scenarios for the model's entities
expand-pattern Expand a named modeling pattern into RIDDL
get-template Return a built-in RIDDL template
list-patterns List the available modeling patterns
list-templates List the built-in templates

Installation Guides

The RIDDL MCP Server can be connected to various AI tools. Choose your platform:

Protocol Details

The stdio server speaks JSON-RPC 2.0 on stdin/stdout; the HTTP server accepts one JSON-RPC message per POST /mcp. Example tools/call request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "riddl_validate",
    "arguments": {
      "source": "domain Example is { ??? }"
    }
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      { "type": "text", "text": "Validation successful: 0 errors, 1 warning" }
    ],
    "isError": false
  }
}

Support

License

The MCP tools are part of riddlg, which is proprietary software with a free tier. See Free and Pro — all MCP tools are free.