MCP Server

The Model Context Protocol (MCP) lets an AI application discover tools, learn their input format, and call them. Devlish’s MCP server makes Devlish programs available through that interface, so a calculation can run as code while the AI application decides when to request it.

This page is the server configuration reference. Follow Your First Tool for a guided example first. MCP provides the connection between client and program; it does not by itself decide whether the program’s external actions are authorized.

Starting the Server

The MCP server runs as a process that a client communicates with through standard input and output. This command starts it; it is separate from Devlish’s HTTP server mode.

devlish mcp

The server communicates over stdin/stdout using JSON-RPC, following the MCP 2024-11-05 protocol.

Tool Discovery

Tool discovery reads manifests in the configured directories. Select the directories explicitly when the default location is not where you keep your programs.

Point the server at directories containing your tools:

devlish mcp --tools-dir ~/.devlish/tools --tools-dir ./my-project/tools

The default tools directory is ~/.devlish/tools/. Each directory is scanned for a devlish.toml manifest that declares available tools.

devlish.toml Manifest

Each tool project contains a devlish.toml that declares metadata and tool definitions:

name = "invoice-processor"
description = "Process and validate invoices"

[[tools]]
name = "validate_invoice"
description = "Validate an invoice against business rules"
source = "validate_invoice.dvl"

  [tools.parameters.invoice_path]
  type = "string"
  description = "Path to the invoice JSON file"
  required = true

  [tools.parameters.strict_mode]
  type = "boolean"
  description = "Whether to enforce all optional rules"

[[tools]]
name = "summarize_invoices"
description = "Produce a summary report for a batch of invoices"
source = "summarize.dvl"

  [tools.parameters.directory]
  type = "string"
  description = "Directory containing invoice files"
  required = true

Built-in Tools

The MCP server always exposes four built-in tools:

Tool	Description
compile	Compile a .dvl source string to bytecode JSON
run	Compile and run a .dvl source string, returning results
validate	Check if source code is syntactically valid
lint	Lint source code and return structured diagnostics

Claude Desktop Configuration

Add Devlish to your Claude Desktop claude_desktop_config.json:

{
  "mcpServers": {
    "devlish": {
      "command": "devlish",
      "args": ["mcp", "--tools-dir", "/path/to/your/tools"]
    }
  }
}

Cursor Configuration

For Cursor, add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "devlish": {
      "command": "devlish",
      "args": ["mcp", "--tools-dir", "./devlish/tools"]
    }
  }
}

How Ask Maps to Tool Inputs

When a .dvl program uses Ask statements, those become tool input parameters. The MCP client provides them as the arguments object:

Ask "What is the project ID?" as project id
Ask "What credit type?" as credit type

The LLM calls the tool with:

{
  "project_id": "PROJ-42",
  "credit_type": "ITC"
}

Input values are injected into the program’s context before execution begins.

Tool Output

Programs that use Respond with return structured JSON to the LLM. Programs that use Print or Export return their output as text content. Failed programs return error messages that the LLM can interpret and retry.