MCP HubMCP Hub
theronic

modex

by: theronic

Modex is a Clojure MCP Library to augment your AI models with Tools, Resources & Prompts using Clojure (Model Context Protocol). Implements MCP Server & Client.

67created 05/03/2025
Visit
Clojure
AI

📌Overview

Purpose: Modex aims to enhance AI capabilities by allowing integration of various tools, resources, and prompts via the Model Context Protocol using native Clojure.

Overview: Modex is a Clojure library that facilitates the development of Model Context Protocol (MCP) servers and clients. It simplifies communication between AI models and external resources, enabling new functionalities without reliance on Java SDKs or proxies.

Key Features:

  • Native Clojure Integration: Offers seamless compatibility with Clojure, eliminating the need for additional Java SDKs or proxy servers, which simplifies usage and implementation.

  • Standardized Transport Protocol: Implements the stdio transport for direct communication, streamlining connections between AI models and the MCP server without intermediary steps.

  • Tool and Resource Definition: Allows developers to define tools, resources, and prompts easily within the Clojure environment, enhancing the extensibility and flexibility of AI applications.

Modex: Model Context Protocol Server & Client Library in Clojure

Modex (MOdel + ContEXt) is a Clojure library that lets you augment your AI with new tools, resources, and prompts.

Modex implements most of the Model Context Protocol to build MCP Servers & Clients in native Clojure.

Because it's native Clojure, you don't need to deal with Anthropic's MCP Java SDK.

Modex implements the stdio transport in the 2024-11-05 MCP spec, so no proxy like mcp-proxy is needed to translate between SSE and stdio.

Table of Contents

  1. Quickstart
  2. What is MCP?
  3. What can Modex do?
  4. Detailed Step-by-Step Instructions
  5. Implementation
  6. Project Status
  7. Rationale
  8. FAQ
  9. License

Example Tools

Datomic MCP uses Modex to expose Datomic tools so your models can query DB schema and data in dev or prod.

Quickstart

  1. git clone git@github.com:theronic/modex.git
  2. cd modex
  3. ./build.sh builds an uberjar at target/modex-mcp-0.2.2.jar.
  4. Open your Claude Desktop Config at ~/Library/Application Support/Claude/claude_desktop_config.json.
  5. Configure a new MCP Server that will run the uberjar at its full path:
{
  "mcpServers": {
    "modex-mcp-hello-world": {
      "command": "java",
      "args": ["-jar", "/Users/your-username/code/modex/target/modex-mcp-0.2.2.jar"]
    }
  },
  "globalShortcut": ""
}
  1. Restart Claude Desktop to activate your new MCP Server + tools.
  2. Tell Claude to "run the inc tool with 123", authorize the tool and you should see an output of 124.

What is MCP?

MCP lets you augment your AI models with Tools, Resources & Prompts:

  • Tools are actions, like querying a database (e.g. Datomic).
  • Resources are files and data it can read, like PDF bank statements.
  • Prompts are templated messages and workflows.

Use Cases

Modex is used by datomic-mcp, which exposes production Datomic databases to an MCP client like Claude Desktop. The AI model diagnoses support queries by reading database schema and running queries that check server states and IPs.

Over time, the goal is to automate recurring support queries using Modex and other MCP tools.

What can Modex do?

Full Example

An MCP server example is in src/modex/mcp/core.clj defining a server with basic tools. Your MCP client (e.g. Claude Desktop) can connect to this server and use exposed tools to provide additional context to AI models.

Data Structures

Tools

A tool is a Tool record with several Parameter arguments:

(defrecord Tool [name doc args handler])
(defrecord Parameter [name doc type required default])

Tools are usually defined with the tool and tools macros.

tool Macro

Defines a single tool with metadata describing parameters, types, and docs. MCP spec currently supports :string and :number parameter types.

(require '[modex.mcp.tools :as tools])

(def add-tool
  (tools/tool
    (add [{:keys [x y]
           :type {x :number
                  y :number}
           :or   {y 0} ; y is optional
           :doc  {x "First number"
                  y "Second number"}}]
         [(+ x y)])))

Invoke a Tool with Validation

(tools/invoke-tool add-tool {:x 5 :y 6})
=> {:success true, :results [11]}

Invoke a Tool Handler Directly (skip validation):

(tools/invoke-handler (:handler add-tool) {:x 5 :y 6})
=> [11]

Define a Toolset with tools Macro

(def my-tools
  (tools/tools
    (greet
      "Greets a person by name."
      [{:keys [first-name last-name]
        :doc {first-name "A person's first name."
              last-name  "A person's last name (optional)."}
        :type {first-name :string last-name :string}
        :or {last-name nil}}]
      [(str "Hello from Modex, "
            (if last-name
              (str first-name " " last-name)
              first-name) "!")])

    (add
      "Adds two numbers."
      [^{:type :number :doc "First number"} a
       ^{:type :number :doc "Second number"} b]
      [(+ a b)])

    (subtract
      "Subtracts two numbers (- a b)"
      [^{:type :number :doc "First number"} a
       ^{:type :number :doc "Second number"} b]
      [(- a b)])

    (error-handling
      "This tool throws intentionally. Modex will handle errors for you."
      []
      (throw (ex-info "Modex will handle exceptions." {})))))

Create a Modex MCP Server + Tools

(require '[modex.mcp.server :as server])

(def my-mcp-server
  (server/->server
    {:name       "Modex MCP Server"
     :version    "0.0.2"
     :initialize (fn [_init-params] "Setup and blocking I/O like connecting to DB.")
     :tools      my-tools
     :prompts    nil    ; Prompts are WIP.
     :resources  nil})) ; Resources are WIP.

Start your MCP Server

(server/start-server! my-mcp-server)

Or put that in your -main function.

Protocols

Modex exposes an AServer protocol describing MCP servers exposing tools, resources & prompts.

(defprotocol AServer
  (protocol-version [this])
  (server-name [this])
  (version [this])
  (capabilities [this])
  (initialize [this _init-params])
  (list-tools [this])
  (call-tool [this tool-name arg-map])
  (list-resources [this])
  (list-prompts [this]))

Detailed Step-by-Step Instructions

Step 1: Build the Uberjar

Build the uberjar, a Java executable:

clojure -T:build uber

or run the helper:

./build.sh

(Make it executable first with chmod +x build.sh if needed).

Step 2: Open Claude Desktop Config

Open your Claude Desktop configuration file:

~/Library/Application Support/Claude/claude_desktop_config.json

Step 3: Configure your MCP Server

Add an element under mcpServers:

{
  "mcpServers": {
    "modex": {
      "command": "java",
      "args": ["-jar", "/Users/your-username/code/modex/target/modex-mcp-0.2.2.jar"]
    }
  },
  "globalShortcut": ""
}

This tells Claude Desktop to start your MCP server process and communicate over stdin/stdout.

Step 4: Restart Claude Desktop

After restarting, you can ask Claude commands like "run foo" or "what does foo say?" and get responses.

Implementation

Modex implements an MCP client & server in Clojure, mostly compliant with the 2024-11-05 MCP Spec.

Messages use JSON-RPC 2.0 format:

  • Requests (id, method, ?params)
  • Responses (id, result, ?error)
  • Notifications (method, ?params)

Transports supported:

  • stdio/stdout (implemented)
  • Server-Sent Events (SSE) (not implemented yet)

Project Status

  • Passing tests
  • Ergonomics (AServer / AClient protocol)
  • Tools
  • nREPL for live changes to running process
  • Resources
  • Prompts
  • [in progress] SSE support
  • [in progress] Streaming HTTP Support (2025-03-26 MCP spec)

Rationale

Existing library mcp-clj uses SSE which requires an SSE <=> stdio proxy. Modex implements stdio directly to avoid this complexity.

FAQ

Can I modify the server while an MCP Client (like Claude Desktop) is connected?

Not yet, but nREPL support is planned to enable eval changes live without rebuilding the uberjar.

Currently, you need to rebuild the uberjar and restart Claude Desktop.

Thank You To Paid Modex Customers

  • Nextdoc – Document Streaming for Salesforce
  • Huppi — Small Business Accounting Software

License

  • Free for non-commercial use: Use, modify, share under GPLv3 at no cost, keeping it open source.
  • Commercial use: For keeping changes private, pay $20 once-off for a perpetual commercial license.

Licensed under the GNU General Public License v3.0 (GPLv3). Use and distribute freely, with derivative works also under GPLv3.

To obtain a commercial license, contact: modex@petrus.co.za

Author(s)