mcp-tkx, User guide

New to MCP or to this library? Start with Getting started for install, your first STDIO server, and a smoke test against the MCP Inspector. Then read Architecture for the session-atom + context-hashmap split, the message lifecycle, and the namespace map.

Trying to understand the kebab-case story? Kebab-case key transformation explains why the wire format and your code disagree on casing, where the conversion happens, and how to wire it up for STDIO and HTTP transports.

Bumping a server to the latest spec? Protocol versions is the version-by-version feature matrix and the negotiation algorithm. 2025-11-25 features walks through what that revision added. 2026-07-28: the stateless revision covers the redesign that followed, which removed the handshake and replaced server-initiated requests.

Validating tool / prompt / resource shapes before shipping? Schema validation covers the Malli schema namespace and the !-suffixed throwing constructors.

Resources whose content changes over time? Dynamic resources covers the :read-fn pattern and when to reach for it vs. static :text / :blob.

Plugging your server into Claude? Claude Desktop / Claude Code setup covers claude_desktop_config.json and claude mcp add, plus the STDIO vs SSE transport choices.

Serving your server over HTTP to modern / remote clients? Streamable HTTP transport covers the current 2025-03-26+ transport: the single /mcp endpoint, Mcp-Session-Id sessions, JSON-or-SSE responses, Last-Event-Id resumability, and how it differs from the older HTTP+SSE example.

Iterating on tools while a client is connected? REPL workflow is the live-development story: add-tool / remove-tool / notify-resource-updated from a REPL.

Lifting a piece of the toolkit into a different MCP server? Extraction recipes is the worked-example index: how to copy the kebab-case transport, the Malli schema registry, the dynamic-resource handler, the session lifecycle, and the cancellation pattern.

If you're picking patterns:

• Building a Clojure MCP server: start at Getting started, then Architecture. Most server work fits the prompt / resource / tool registration pattern; you don't need to touch impl/.
• Wiring an MCP server into a different JSON-RPC framework: the Extraction recipes Recipe 1 lifts the kebab-case transport pattern out of the toolkit. The schema validation in Recipe 2 is independent of MCP.

See bb tasks for the full list. The 30-second version:

bb test                      # run all tests via kaocha
bb dev                       # nREPL on :7777 with CIDER middleware
bb example:server:stdio      # run example STDIO server
bb example:server:sse        # run example SSE server (clj-server-sse)
bb example:server:streamable-http  # run example Streamable HTTP server (2025-03-26+)
bb example:server:streamable-http:2026  # run example Streamable HTTP server (2026-07-28, stateless)
bb example:client:stdio      # run example STDIO client
bb info                      # grouped, categorised cheat-sheet of all tasks
bb tasks                     # list every task with its docstring

Babashka

The library runs on Babashka, and bb bb:smoke proves it by driving a real tools/list and tools/call through a server session rather than just requiring the namespaces. Loading is the easy half, and both problems below sit behind a successful require. bb ci runs it as step 5, so it cannot rot quietly. On a Babashka too old to run it, the gate warns and carries on rather than failing, since this project's :min-bb-version is 1.3.0.

Two things are needed, and neither alone is enough. Babashka 1.13.220 or newer, because earlier versions have no java.util.concurrent.locks.ReentrantLock and promesa.util imports it unconditionally. And promesa 12, because promesa 11 has a deftype implementing java.util.function.Supplier that SCI rejects.

That promesa version is supplied by the :babashka alias in deps.edn rather than by the project pin, because promesa 12 carries a ClojureScript regression that json_rpc.cljc walks straight into. A p/handle whose function returns a Throwable rejects with promesa's own wrapper promise instead of the exception, so the p/catch after it receives a PromiseImpl, ex-message is nil, and every error response quietly loses its reason. A plain p/catch is unaffected, and so is the JVM. It takes that one shape on that one platform, which is how it reached a release. Reported as promesa#171. The two problems land on opposite sides of the platform split, so the override is scoped to the one runtime that needs it.

Consuming this library on Babashka means doing the same in your own deps.edn, since the pin you inherit is promesa 11:

{:aliases {:babashka {:override-deps {funcool/promesa {:mvn/version "12.0.1"}}}}}

• Pagination: not wired through prompts/list, resources/list or tools/list. Implementations leave a #_#_:next-cursor "next-page-cursor" placeholder in the handler.

• Project README: protocol and feature support table, the dynamic-resources capability row, other-MCP-libs comparison.
• CHANGELOG.md: version history per release. Two unreleased entries: v2026-07-28 covers the stateless revision, and v2025-11-25 covers the 9 phases of the upstream-spec port (Phase 0 = kebab-case transport, Phase 1 = protocol negotiation, Phase 2 = server description, Phase 3 = icons, Phase 4 = Malli schemas, Phase 5 = sampling with tools, Phase 6 = elicitation, Phase 7 = tasks, Phase 9 = JSON Schema 2020-12 dialect).
• docs/reference/: preserved upstream Metosin docs (api-design.md, session.md, context.md, using-the-library.md, repl-story.md, MIGRATION-2025-06-18.md).
• MIGRATION-2025-06-18.md: the older migration writeup (added by upstream when bumping from 2025-03-26 → 2025-06-18).