ModelContextProtocol.jl

Julia implementation of the Model Context Protocol (MCP), enabling seamless integration between AI applications and external data sources, tools, and services.

Features

  • ✅ Dual-Era Protocol Support - the full 2026-07-28 modern era (stateless requests, server/discover, MRTR, the tasks extension, argument completion, subscriptions, header parameter mirroring, per-request logging) alongside classic sessions negotiated from 2025-11-25 back to 2024-11-05
  • ✅ Multiple Transports - stdio (default) and Streamable HTTP with Server-Sent Events and session management
  • ✅ All Content Types - text, images, audio, embedded resources, and resource_link references
  • ✅ Structured Tool Output - output_schema declarations with structuredContent results
  • ✅ Tool Annotations - behavioral hints (readOnlyHint, destructiveHint, …) for client trust decisions
  • ✅ Progress Notifications - long-running tools report progress through context-aware handlers
  • ✅ Background Tasks - the modern-era tasks extension (server-directed handoff, mid-task input, status notifications) plus legacy SEP-1686 tasks for 2025-11-25 sessions
  • ✅ Argument Completion - completion/complete suggestions for prompt arguments and template variables
  • ✅ OAuth Resource Server - bearer-token validation for HTTP (JWKS signature verification, GitHub tokens, JWT claims, RFC 7662 introspection) with RFC 9728 discovery
  • ✅ Logging Control - runtime logging/setLevel (legacy) and per-request logLevel opt-in (modern)
  • ✅ Auto-Registration - automatic component discovery from directory structure
  • ✅ Type-Safe - leverages Julia's type system for robust implementations

Note: This is a server-side implementation. Legacy-era server-initiated elicitation/sampling (the modern era covers these via MRTR) and the OAuth Authorization Server (token issuance) are not implemented; SSE streams are not resumable via Last-Event-ID, and synchronous requests are served on a single serial loop (tasks move long tool calls off-loop).

Installation

using Pkg
Pkg.add("ModelContextProtocol")

Quick Start

Create a simple MCP server with a tool:

using ModelContextProtocol

# Create a server with a simple echo tool
server = mcp_server(
    name = "echo-server",
    version = "1.0.0",
    tools = [
        MCPTool(
            name = "echo",
            description = "Echo back the input message",
            parameters = [
                ToolParameter(
                    name = "message",
                    type = "string",
                    description = "Message to echo",
                    required = true
                )
            ],
            handler = (params) -> TextContent(text = params["message"])
        )
    ]
)

# Start the server (stdio transport by default)
start!(server)

Using HTTP Transport

For web-based integrations, use the HTTP transport:

# Create server, then attach an HTTP transport
server = mcp_server(
    name = "http-server",
    version = "1.0.0",
    tools = MCPTool[]  # Your tools here
)

server.transport = HttpTransport(host = "127.0.0.1", port = 3000)
connect(server.transport)
start!(server)

# Test with curl
# curl -X POST http://127.0.0.1:3000/ \
#   -H "Content-Type: application/json" \
#   -d '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":1}'

Documentation Structure

Protocol Compliance

ModelContextProtocol.jl serves the full MCP 2026-07-28 modern era statelessly, alongside classic sessions negotiated at 2025-11-25 down through 2025-06-18 and 2025-03-26 to 2024-11-05. This includes:

  • JSON-RPC 2.0 message protocol (batching rejected per spec)
  • Tool discovery and invocation, structured output, annotations, _meta
  • Resource management with subscriptions and resource_link references
  • Prompt templates with arguments and media content; argument completion
  • Progress notifications (notifications/progress) and logging (logging/setLevel for sessions, per-request logLevel in the modern era)
  • Session management and OAuth Resource Server authentication for HTTP transport
  • Modern-era tasks, MRTR, subscriptions/listen, and SEP-2243 header validation

Basic Concepts

Tools

Tools are functions that can be invoked by the LLM:

tool = MCPTool(
    name = "calculate",
    description = "Perform basic arithmetic",
    parameters = [
        ToolParameter(name = "a", description = "First operand", type = "number", required = true),
        ToolParameter(name = "b", description = "Second operand", type = "number", required = true),
        ToolParameter(name = "op", description = "Operator: +, -, * or /", type = "string", required = true)
    ],
    handler = function(params)
        a, b = params["a"], params["b"]
        result = if params["op"] == "+"
            a + b
        elseif params["op"] == "-"
            a - b
        elseif params["op"] == "*"
            a * b
        elseif params["op"] == "/"
            a / b
        else
            error("Unknown operation")
        end
        return TextContent(text = string(result))
    end
)

Resources

Resources provide data access to the LLM:

resource = MCPResource(
    uri = "file:///data/config.json",
    name = "Application Config",
    description = "Current application configuration",
    mime_type = "application/json",
    data_provider = () -> JSON3.read(read("config.json", String), Dict{String,Any})
)

Prompts

Prompts are templates for generating conversations:

prompt = MCPPrompt(
    name = "code_review",
    description = "Request a code review",
    arguments = [
        PromptArgument(
            name = "language",
            description = "Programming language",
            required = true
        )
    ],
    messages = [
        PromptMessage(
            content = TextContent(
                text = "Please review this {language} code for best practices."
            )
        )
    ]
)

Template placeholders like {language} are substituted from the arguments supplied in prompts/get.

Testing Your Server

With MCP Inspector

Test your server using the official MCP Inspector:

# For stdio transport (Inspector spawns the server command directly)
npx @modelcontextprotocol/inspector julia --project=. server.jl

# For HTTP transport
npx @modelcontextprotocol/inspector http://127.0.0.1:3000/

# Quick smoke test without the browser UI (CLI mode)
npx @modelcontextprotocol/inspector --cli julia --project=. server.jl --method tools/list

With curl (HTTP only)

# Initialize connection
curl -X POST http://127.0.0.1:3000/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}},"id":1}'

# List available tools
curl -X POST http://127.0.0.1:3000/ \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: <session-id-from-init>" \
  -d '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":2}'

Next Steps

Contributing

ModelContextProtocol.jl is part of the JuliaSMLM organization. Contributions are welcome! Please see our GitHub repository for issues and pull requests.

License

This project is licensed under the MIT License.