Skip to content
b12n-ossPublic

About

Clojure and ClojureScript library for building Model Context Protocol clients and servers. Five protocol revisions, dual-era sessions, runs on the JVM, Node and Babashka.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Latest commit

 

History

270 Commits

Folders and files

mcp-tkx

Build Model Context Protocol clients and servers in Clojure and ClojureScript.

mcp-tkx is an independently maintained fork of metosin/mcp-toolkit. It speaks all five MCP protocol revisions: four negotiate at the handshake, and 2026-07-28 removed the handshake, so a session opts into it explicitly. It keeps your handler code in kebab-case while the wire stays camelCase, and does no I/O of its own, so you can put it behind STDIO, HTTP+SSE, Streamable HTTP, or anything else that can move JSON.

We have used this internally for a good while now, across a number of our own projects, and exercised it against Claude Desktop and Claude Code. 236 tests run across Clojure and ClojureScript. The API has held stable in practice, though it carries no formal compatibility guarantee yet.

Install

There is no Clojars release. Depend on it by git tag:

{:deps {io.github.b12n-oss/mcp-tkx
        {:git/tag "v2026-07-28" :git/sha "6ab2a10"}}}

Tags are what to pin to. They move only when a release is cut, so your build does not change under you, and the pair is checked: tools.deps verifies the sha really is that tag.

To take the tip instead, or to check what the newest tag is:

clojure -X:deps git-resolve-tags          # rewrites tags in deps.edn to their shas
gh api repos/b12n-oss/mcp-tkx/tags --jq '.[0].name'

No :git/url is needed now the repo is public. It used to carry one, because while the repo was private the shorthand resolved to an unauthenticated https:// URL and failed even for someone with SSH access.

Examples inside this repo use :local/root "../.." instead.

Quickstart

A server with one tool, over STDIO:

(require '[mcp-toolkit.server :as server]
         '[mcp-toolkit.json-rpc :as json-rpc])

(def greet-tool
  {:name         "greet"
   :title        "Greet someone"
   :description  "Returns a greeting."
   :input-schema {:type       "object"
                  :properties {"name" {:type "string"}}
                  :required   ["name"]}
   :tool-fn      (fn [context {:keys [name]}]
                   {:content [{:type "text"
                               :text (str "Hello, " name)}]})})

(def session
  (atom
    (server/create-session
      {:server-info {:name "my-server" :version "0.1.0"}
       :tools       [greet-tool]})))

You supply the transport by giving the context a :send-message fn and feeding decoded messages into json-rpc/handle-message. The four projects under example/ show that wiring for STDIO, HTTP+SSE and Streamable HTTP.

Full walkthrough: Getting started.

What this fork adds

What it gives you
Kebab-case end to end Handlers see :max-tokens and :input-schema. The camelCase conversion lives in the transport layer, so no handler does field renaming.
Malli protocol registry mcp-toolkit.schema types the protocol itself: icons, sampling requests, elicitation, tasks, content blocks. valid? / validate / explain, plus !-suffixed throwing constructors.
Dynamic resources A resource can compute its content at resources/read time through :read-fn, returning :text, :blob, :contents or :error, or a Promesa promise of any of them.
Five revisions, one build 2024-11-05 through 2025-11-25 negotiate at the handshake. 2026-07-28 removed the handshake, so a session opts into it explicitly.
Cancellation that reaches your handler A per-request is-cancelled atom plus a notifications/cancelled handler, so long-running work can actually stop.
Streamable HTTP reference server A complete implementation with sessions, the JSON-or-SSE response flip, Last-Event-Id resumability and Host/Origin validation.

Protocol and feature support

2024-11-05, 2025-03-26, 2025-06-18 and 2025-11-25 negotiate automatically at the initial handshake. 2026-07-28 removed the handshake, so a session opts into it explicitly, with one exception for a session serving both eras at once: see the dual-era negotiation notes in Protocol versions.

JSON-RPC batching was removed in 2025-06-18. Note that this library rejects array requests on every version, not only that one, so a 2024-11-05 or 2025-03-26 client that sends a batch gets -32600 Invalid Request back. See json_rpc.cljc, which does not consult the negotiated version before rejecting.

Capability Since Status
Prompts, resources, tools 2024-11-05 Full
Cancellation, ping, progress 2024-11-05 Full
Roots 2024-11-05 Full
Sampling 2024-11-05 Full
Completion, logging 2024-11-05 Full
Title fields 2025-06-18 Full
_meta passthrough 2025-06-18 Partial, see below
Output schema on tools/list 2025-06-18 Advertised, results not validated
Resource links 2025-06-18 Not implemented
Elicitation, form and URL 2025-11-25 Partial, see below
Sampling with tools 2025-11-25 Full
Icons 2025-11-25 Partial, see below
Server description 2025-11-25 Full
JSON Schema 2020-12 dialect 2025-11-25 Full
Tasks 2025-11-25 Experimental, as in the spec; also Partial, see below
Stateless core, no handshake 2026-07-28 Full, server and client
server/discover 2026-07-28 Full, server and client
Multi Round-Trip Requests 2026-07-28 Full, server and client
resultType on every result 2026-07-28 Full
ttlMs and cacheScope on cacheable results 2026-07-28 Full
Deterministic list ordering 2026-07-28 Full
Renumbered error codes 2026-07-28 Full
subscriptions/listen 2026-07-28 Full, server and client
Dual-era serving, both on one session 2026-07-28 Full in the library, not in the example HTTP transport
Tasks as an extension 2026-07-28 Not implemented
Streamable HTTP Mcp-Method / Mcp-Name headers 2026-07-28 Not implemented
Dynamic resources via :read-fn fork Full
Pagination any Not implemented
What the partial rows mean

Icons. The spec puts icons?: Icon[] on tools, prompts, resources and server info, where each Icon is an object with src, and optionally mimeType, sizes and theme. This library ships a singular :icon holding a bare URI string, and does not attach icons to server info at all. A spec-conforming client will therefore not see an icon. Treat it as a working convention inside this library rather than as spec support.

_meta passthrough. Inbound _meta reaches your handler, and a _meta you put on a result travels back out. But the prompts/list, resources/list and tools/list handlers select a fixed set of keys and drop :_meta from each entry, so metadata attached to a registration does not appear in listings.

Elicitation. This library builds both clients and servers, and the server side can request elicitation (request-elicitation). But a client built with this library has no elicitation/create handler. impl/client/handler.cljc registers only ping, roots/list, sampling/createMessage, and the notification callbacks. A client built with this library answers -32601 Method not found to an elicitation request, so elicitation only works when your server talks to a third-party client that implements it.

Tasks. Same gap as elicitation, on both sides. The server side can send tasks/get / tasks/result / tasks/cancel / tasks/list to the client (request-task-get and friends), but there is no inbound handler for any tasks/* method on either impl/server/handler.cljc or impl/client/handler.cljc. Tasks only work end to end against a third-party implementation that has its own tasks/* handler, which lines up with the spec's own experimental status for this capability.

Runtimes, content blocks, and what is missing

Runtimes

Runtime Status
Clojure (JVM) Supported
ClojureScript (Node, shadow-cljs) Supported
Babashka Supported, and bb bb:smoke drives a real tools/list and tools/call there to prove it. Needs Babashka 1.13.220 or newer plus promesa 12, which the :babashka alias supplies because the project pin stays on promesa 11 for ClojureScript's sake. Detail.

Content block types

Supported: text, image, audio, tool_use, tool_result.

Not implemented: resource_link and embedded resource blocks. A tool returns content, so it cannot yet hand back a resource reference alongside it.

Pagination

prompts/list, resources/list and tools/list return a single full page. The cursor field is stubbed out in the handlers rather than implemented, so a client expecting to page through results gets everything at once instead.

Examples

Four directories live under example/ and share their MCP content through common-mcp-content, so the transports are directly comparable. clj-server-streamable-http ships two servers, one per protocol era, so the table below has five rows.

Example Transport Run it
cljc-server-stdio STDIO server bb example:server:stdio
cljc-client-stdio STDIO client bb example:client:stdio
clj-server-sse HTTP+SSE, 2024-11-05, deprecated bb example:server:sse
clj-server-streamable-http Streamable HTTP, 2025-03-26+ bb example:server:streamable-http
clj-server-streamable-http Streamable HTTP, 2026-07-28, stateless bb example:server:streamable-http:2026

Documentation

The user guide is the place to start. Thirteen more pages cover the architecture, all five protocol revisions, schema validation, both HTTP transports, the REPL workflow, a container smoke test, and recipes for lifting pieces of this into other projects.

Guide contents
Page What it covers
Getting started Install, first STDIO server, smoke test against MCP Inspector
Architecture Session atom, context hashmap, message lifecycle, namespace map
Kebab-case transformation Where the casing boundary sits, and how to wire it per transport
Protocol versions The negotiation algorithm and what each revision adds
Schema validation The Malli registry and the throwing constructors
Dynamic resources :read-fn, its return contract, and when to prefer static content
2025-11-25 features Elicitation, tasks, sampling with tools, icons
2026-07-28: the stateless revision The redesign that removed the handshake, and what replaced it
Claude Desktop setup claude_desktop_config.json and claude mcp add
Streamable HTTP The current remote transport, end to end
REPL workflow Editing tools while a client stays connected
Docker + REPL smoke test Driving a containerised server with this library's own client
Extraction recipes Lifting the transport or the schema registry elsewhere

Reference material lives in docs/reference/. Most of it is preserved from upstream, but only MIGRATION-2025-06-18.md carries a preserved-from-upstream banner, since it is the only file that still shows upstream coordinates. The other migration guide, 2025-11-25, is this fork's own work.

Build and test

bb test      # full suite, Clojure and ClojureScript, via kaocha
bb check     # compile and lint, run this before committing
bb coverage  # test coverage report, JVM only, see below
bb site:serve # build and preview the documentation site locally
bb info      # categorised cheat-sheet of every task

bb check and bb ci shell out to clj-kondo, and the ClojureScript half of bb test needs the ws package package.json declares, so run npm install once at the repo root. That second one only bites on Node 20 and older: Node 22 has a built-in WebSocket and never reaches for it, which is exactly why it is easy to ship broken.

bb docker:verify   # run the whole gate in a clean container

bb docker:verify builds from a copy that obeys .dockerignore, which mirrors .gitignore, so the container sees what a fresh clone sees and none of your own caches or untracked files. It is the answer to "works on my machine", and it has already earned its keep: .clj-kondo was ignored wholesale, so a clone had none of the linter configs libraries export and bb check failed on code that was fine. Every existing checkout had a warm cache and could not see it.

bb coverage runs cloverage and writes an HTML report to target/coverage/index.html. It measures only the JVM run, because cloverage does not support ClojureScript. That covers the whole library anyway: src/ contains no reader conditionals, so every line the ClojureScript build compiles is exercised on the JVM too. Nothing fails on a coverage number; it is a report to read, not a gate.

Other MCP projects in Clojure

The ecosystem moved quickly, and there are now several libraries to choose between. Approaches differ mainly in whether they implement the protocol in Clojure or wrap the official Java SDK, so that is the column worth scanning.

Library Approach
plumcp Clojure and ClojureScript, servers and clients. The closest sibling to this one.
mcp-clj Pure Clojure, minimal dependencies, self-contained REPL integration
MCP Clojure SDK Servers, with clients planned
Modex Servers and clients, covering tools, resources and prompts
mcp-server Lightweight and dependency-light, self-described as alpha
Gaiwan mcp-sdk Pure Clojure, STDIO and HTTP transports
latacora/mcp-sdk A Ring adapter over the official Java SDK
MCP 2000XL Wraps the Java SDK, leaves the transport to you

Servers and tooling, if you want something to run rather than something to build on:

  • Clojure MCP, an MCP server giving assistants a Clojure REPL and editing tools
  • clojure-mcp-light, the same idea as plain CLI tools, deliberately not an MCP server
  • Calva's Backseat Driver, a VS Code extension that can also act as an MCP server
  • repl-mcp, REPL integration plus development tooling over MCP

Acknowledgements

This library began as Metosin's mcp-toolkit, and the architecture that makes it pleasant to work with is theirs: the session atom, the I/O-agnostic core, the Promesa-based handler contract. That design carried every feature added here without needing to be rethought, which is the best thing you can say about a foundation.

Source namespaces are still mcp-toolkit.*, so this remains a drop-in replacement. Only the project name and the build coordinates differ.

Why this is a fork rather than pull requests

Upstream states its contributing policy plainly:

Only code typed and reviewed by a human will be accepted for review, discussion, and maybe merged. We have a policy of keeping the source code clean, organized, and easy to read for a human.

The work in this fork is LLM-assisted, so it falls outside that policy. Opening pull requests that upstream has already said it cannot accept would only cost a maintainer their time, so the changes are maintained here instead. Setting that bar is upstream's call and a reasonable one to make.

There is a practical driver as well. Some of our internal libraries and tools are built on this one, and we plan to open source a few of them. Anything we publish needs its dependencies to exist as real projects that other people can resolve, and the changes those tools rely on are exactly the ones upstream cannot take. Holding those changes as a private patch set would leave everything built on top of them unpublishable too. Giving the fork its own name, coordinate and history is what makes opening up that work possible at all.

EPL-2.0 exists so an independent continuation like this one can happen without either side needing to agree.

Contributing

Issues and pull requests are welcome. CONTRIBUTING.md covers the gate (bb ci, and the suite staying at 236 tests), the traps that have actually cost someone a session, and where this project's line on AI-assisted contributions differs from upstream's.

Also here: a code of conduct, and a security policy with what is in scope for a report and what belongs in your transport instead. Vulnerabilities go through private reporting, not a public issue.

License

Distributed under the Eclipse Public License v2.0.

Copyright (c) Metosin and contributors. Copyright (c) 2026 the mcp-tkx contributors.

About

Clojure and ClojureScript library for building Model Context Protocol clients and servers. Five protocol revisions, dual-era sessions, runs on the JVM, Node and Babashka.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

⌂