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.
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.
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 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. |
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
| 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. |
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.
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.
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 |
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.
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 taskbb 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 containerbb 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.
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
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.
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.
Distributed under the Eclipse Public License v2.0.
Copyright (c) Metosin and contributors.
Copyright (c) 2026 the mcp-tkx contributors.