Skip to content
Back to search

mcp-shuttle

MCP server and client for Clojure: a Ring handler and a JDK HttpClient client

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/rosetta-oss--mcp-shuttle/badge.svg)](/listings/rosetta-oss--mcp-shuttle)

HTML

<a href="/listings/rosetta-oss--mcp-shuttle"><img src="/api/listings/rosetta-oss--mcp-shuttle/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

`deps.edn`, as a git dependency (the SHA is the tag's commit, listed on the release page):

io.github.rosetta-oss/mcp-shuttle {:git/tag "v0.1.0" :git/sha "1d5aa1b"}

Needs Java 21 or later. Changes are in [CHANGELOG.md](CHANGELOG.md).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 115 lines
  1. # mcp-shuttle
  2. MCP ([Model Context Protocol](https://modelcontextprotocol.io/)) server and client for Clojure. The server is a plain Ring
  3. handler; the client uses the JDK's HttpClient.
  4. Status: early. Server (HTTP transport, protocol core, tools with malli schemas) and client work and
  5. are tested, in two profiles; sessions for server push and protocol 2025-11-25 are next.
  6. ## Install
  7. `deps.edn`, as a git dependency (the SHA is the tag's commit, listed on the release page):
  8. ```clojure
  9. io.github.rosetta-oss/mcp-shuttle {:git/tag "v0.1.0" :git/sha "1d5aa1b"}
  10. ```
  11. Needs Java 21 or later. Changes are in [CHANGELOG.md](CHANGELOG.md).
  12. ## Layers
  13. | Namespace | What |
  14. |---|---|
  15. | `shuttle.core` | The protocol without a transport: a decoded JSON-RPC message, the caller's context and the revision in; the JSON reply out. |
  16. | `shuttle.tools` | Tools as data with malli schemas: announced as JSON Schema, arguments decoded and checked before the handler runs, optional output schema and `structuredContent`, per-tool timeout, per-caller visibility. |
  17. | `shuttle.http` | Ring handler: Streamable HTTP and HTTP+SSE, authentication, rate limit, body limit, Origin check, batches. |
  18. | `shuttle.client` | Client over Streamable HTTP. |
  19. ## What it does
  20. - Streamable HTTP (`POST /mcp`, protocol 2025-03-26 and 2025-06-18) and the older HTTP+SSE
  21. transport (`GET /mcp/sse`, `POST /mcp/messages`, 2024-11-05).
  22. - Version negotiation, JSON-RPC batches, `tools`, `resources`, `prompts`, `instructions`.
  23. - No sessions on Streamable HTTP: every request stands alone, so restarts and several instances
  24. need nothing special.
  25. - Everything a host decides is injected: who the caller is (`:authenticate`), which tools that
  26. caller sees (`:tools-list`, given the caller's context), what a call does (`:call-tool`), rate
  27. limiting, body size limit, fault logging.
  28. - A tool that refuses (`{:error …}`) and a tool that throws are kept apart: the first becomes an
  29. `isError` result the agent can act on, the second a generic message with a reference; the
  30. exception text never reaches the client.
  31. ## Use
  32. ```clojure
  33. (require '[shuttle.http :as mcp] '[shuttle.tools :as tools])
  34. (def my-tools
  35. [{:name "echo"
  36. :description "Echoes its text"
  37. :input [:map [:text :string]]
  38. :output [:map [:said :string]]
  39. :handler (fn [ctx {:keys [text]}] {:said text})}])
  40. (def handler
  41. (mcp/routes
  42. (merge
  43. (tools/deps my-tools) ; :tools-list and :call-tool
  44. {:authenticate (fn [request]
  45. (when-let [caller (lookup-key (mcp/bearer request))]
  46. {:id (:id caller) :ctx caller}))
  47. :server-info {:name "my-service" :version "1.0.0"}
  48. :unauthorized-message "Send your service key as a Bearer token."
  49. :sse-writer (fn [write!] (ring-streaming-body write!))})))
  50. ```
  51. `routes` returns nil for any other path, so it composes with a host's own routes. See the docstrings
  52. of `shuttle.http` and `shuttle.tools` for every injected function and tool option. A tool refuses by
  53. returning `{:error …}` (sent to the agent as JSON) and fails by throwing.
  54. ## Two profiles
  55. | | `routes` (build) | `data-routes` (data) |
  56. |---|---|---|
  57. | For | people and their agents (Claude Code, agent builders) | programs: other services, batch jobs |
  58. | Path | `/mcp` (+ `/mcp/sse`, `/mcp/messages`) | `/mcp/data`, POST only |
  59. | Offers | tools, resources, prompts, instructions | tools only |
  60. | Limits | optional | `:rate-limit?` and `:max-body-bytes` required (`mcp/rate-limiter`) |
  61. | Tools | `tools/deps` | `tools/data-deps`: every tool needs `:output` and `:timeout-ms` |
  62. | Failures | readable text | JSON with a stable `code`: `invalid_arguments`, `unknown_tool`, `timeout`, `internal_error` (+ `reference`), or the tool's own |
  63. A host can mount both, with different tool sets and limits.
  64. ## Client
  65. ```clojure
  66. (require '[shuttle.client :as mcp-client])
  67. ;; one call: initialize, call, close
  68. (mcp-client/call-tool {:url "http://host:port/mcp" :bearer key :timeout-ms 180000} "templates" {:limit 200})
  69. ;; several calls
  70. (let [c (mcp-client/connect {:url "http://host:port/mcp" :bearer key})]
  71. (try (mcp-client/list-tools c) (finally (mcp-client/close c))))
  72. ```
  73. Every failure throws an `ex-info` (HTTP status, JSON-RPC error, `isError`, unreadable answer,
  74. timeout, no connection); nothing is printed and nothing silently returns nil. Event-stream answers
  75. and server sessions are handled, including initializing again once when a server forgets a session.
  76. ## Develop
  77. ```
  78. clojure -M:test
  79. ```
  80. The test `the-wire-knows-no-business` scans the library's source: it must never learn a host's
  81. vocabulary.
  82. ## License
  83. Copyright (c) 2026 mcp-shuttle contributors.
  84. Eclipse Public License 2.0, see [LICENSE](LICENSE). Code taken from
  85. [PluMCP](https://github.com/plumce/plumcp) (EPL-1.0, Shantanu Kumar) keeps its original copyright
  86. notice and names its source in the file header.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.