mcp — MCP server for Haskell

A complete server implementation of the Model Context Protocol (MCP) for Haskell, built on Servant.

Implements MCP protocol version 2025-06-18. Re-exports the core protocol types from mcp-types for convenience.

Modules

• MCP.Server — Re-exports everything below for convenience.
• MCP.Server.Common — Transport-agnostic core: types, state management, request routing, ProcessHandlers, ToolHandler framework.
• MCP.Server.HTTP — Servant-based HTTP transports with streaming SSE responses at the /mcp endpoint. Provides both a JWT-authenticated API (MCPAPI / mcpAPI) and a simple unauthenticated API (SimpleHTTPAPI / simpleHttpApp) for local development or use behind a reverse proxy.
• MCP.Server.Stdio — Stdio transport reading/writing JSON-RPC messages line-by-line, suitable for subprocess-based integrations.

Install

build-depends:
    base
  , servant
  , servant-server
  , servant-auth-server
  , aeson
  , mcp

If you only need the protocol types (e.g. for a client), depend on mcp-types instead.

Quick Start

{-# LANGUAGE DataKinds #-}
{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE TypeFamilies #-}

import Control.Concurrent.MVar (newMVar)
import MCP.Server

-- Define your handler state and user types
type instance MCPHandlerState = ()
type instance MCPHandlerUser  = MyUser

-- Create server state with capabilities
mkServerState :: IO (MVar MCPServerState)
mkServerState = do
  let impl = Implementation "my-server" "1.0.0" Nothing
      caps = ServerCapabilities
        { logging      = Nothing
        , prompts      = Nothing
        , resources    = Nothing
        , tools        = Just (ToolsCapability { listChanged = Just True })
        , completions  = Nothing
        , experimental = Nothing
        }
      handlers = withToolHandlers myTools defaultProcessHandlers
  newMVar $ initMCPServerState () Nothing Nothing caps impl Nothing handlers

-- Define tools using the ToolHandler framework
myTools :: [ToolHandler]
myTools =
  [ toolHandler "greet" (Just "Say hello") greetSchema $ \_args ->
      return $ ProcessSuccess $ toolTextResult ["Hello!"]
  ]

A fully documented example server lives in mcp-server/example/.

Features

• Three transports: HTTP with JWT auth, simple unauthenticated HTTP, and stdio
• JWT authentication via servant-auth-server (authenticated HTTP transport)
• Simple HTTP for local development or behind a reverse proxy (simpleHttpApp)
• Extensible handler framework: ProcessHandlers record with optional handlers for each MCP method
• Tool helpers: ToolHandler, toolHandler, withToolHandlers, toolTextResult, toolTextError
• Server-to-client requests: ProcessClientInput for sampling, elicitation, and other client callbacks on both transports
• MCP 2025-06-18: Full protocol version support

License

MPL-2.0