mcp-toolkit

MCP Toolkit is a Clojure-based library aimed at simplifying the creation of MCP servers and clients. It provides an API surface for handling core MCP concepts such as prompts, resources, tools, and completion within a CLJC (Clojure/ClojureScript) environment. The toolkit is designed to be paired with example projects that demonstrate how to expose a server interface (via STDIO or HTTP/SSE) and how to develop server components (prompts, resources, and tools) interactively while the server runs. Developers can leverage the included examples to understand how to structure an MCP server in Clojure, how to wire in prompts, resources, and tools, and how to interact with clients through the MCP protocol. Documentation and CLJDocs provide guidance on extending the server and integrating new capabilities.

To use the toolkit, start from the example projects under example/ (for instance, the CLJC server using STDIO or the CLJ server using HTTP/SSE). These serve as concrete references for implementing your own server and developing its components in REPL-driven workflows. The library emphasizes an I/O-agnostic approach, so you can adapt it to different transport layers as needed, while maintaining a consistent MCP protocol surface for clients.

Prerequisites:

• Docker (recommended for the provided containerized setup) or a local Clojure development environment for building from source
• Basic knowledge of MCP protocol concepts (prompts, resources, tools, and prompts execution)

Option A - Run via Docker (recommended for quick start):

1. Install Docker following your platform instructions.
2. Pull and run the toolkit image: docker pull metosin/mcp-toolkit docker run -i metosin/mcp-toolkit
3. If you need to customize environment variables, pass them with -e VAR=value to docker run.

Option B - Local development with Clojure (if you have source and a build workflow):

1. Ensure you have Clojure tooling (e.g., clj/dep.edn or deps.edn configured project).
2. Clone the repository containing the MCP Toolkit and navigate to the project root.
3. Add dependencies as per the project’s build configuration (deps.edn or project.clj).
4. Start the server using your usual CLJ/CLJS startup command, for example, a REPL-driven run or a script that launches the MCP server components.

Notes:

• The repository provides example projects to help you bootstrap an MCP server in CLJC (STDIO) or CLJ (HTTP/SSE). Use those as references when configuring your own environment.
• If you plan to publish a containerized server, consider building a docker image from the project and tagging it for your environment.

Tips and common issues:

• The toolkit targets CLJC development with support for prompts, resources, and tools. When extending, aim to keep IO-agnostic design so you can switch transport layers with minimal changes.
• Consult the example projects under example/ for concrete patterns on wiring prompts, resources, and tools into a running server.
• If you encounter protocol version mismatches, verify the server supports the MCP protocol version you are using (e.g., 2024-11-05, 2025-03-26) and update dependencies accordingly.
• Ensure environment-specific configuration (like transport endpoints or logging) is correctly set up in your deployment environment to avoid silent failures.