ModelContextProtocol.jl

ModelContextProtocol.jl provides Julia server and client utilities for the Model Context Protocol (MCP). It supports Streamable HTTP servers and clients, local subprocess clients, discovery manifests, OAuth-protected resources, JSON-RPC request handling, tools, prompts, resources, completions, and logging notifications.

The package supports the stateful MCP 2025-11-25 protocol and the stateless MCP 2026-07-28 protocol over Streamable HTTP. Clients default to 2025-11-25 for compatibility. See MCP 2026-07-28 for modern client setup, capability checks, multi-round-trip results, custom headers, and subscriptions.

See MCP Events for authenticated webhook subscriptions, signed callbacks, persistence, and client helpers.

For a server launched as a local command, see the stdio client guide. The same initialization, list, and call APIs work with an owned child process.

For deployments that require a concrete request graph, see the trim-safe static server. This API stays under the ModelContextProtocol namespace because it is a specialized alternative to the general server.

Installation

This JuliaServices package is currently unregistered. The General registry has a separate package with the same name, so Pkg.add("ModelContextProtocol") does not install this checkout.

Use a URL or local development checkout instead:

using Pkg
Pkg.develop(url="https://github.com/JuliaServices/ModelContextProtocol.jl")

Server

using ModelContextProtocol

server = MCPServer(MCPServerConfig(
    name="Calculator",
    version="0.1.0",
    transport_path="/v1/mcp",
))

register_tool!(
    server;
    name="add",
    description="Add numbers.",
    input_schema=Dict(
        "type" => "object",
        "properties" => Dict(
            "numbers" => Dict(
                "type" => "array",
                "items" => Dict("type" => "number"),
                "minItems" => 2,
            ),
        ),
        "required" => ["numbers"],
    ),
    handler=function (_context, args)
        numbers = Float64.(args["numbers"])
        result = sum(numbers)
        return Dict(
            "content" => [Dict("type" => "text", "text" => string(result))],
            "structuredContent" => Dict("sum" => result),
        )
    end,
)

http_server = serve_mcp_http(server; host="127.0.0.1", port=3010)
wait(http_server.http)

Agentif Tools

If Agentif.jl is loaded, ModelContextProtocol.jl can register Agentif tools directly through its package extension:

using Agentif
using ModelContextProtocol

tool = @tool "Echo text." echo(text::String) = text

server = MCPServer(MCPServerConfig(name="Agentif MCP", version="0.1.0"))
register_tool!(server, tool)

The extension derives the MCP inputSchema from Agentif.parameters(tool) and wraps the Agentif function in a standard MCP tool handler.

Client

using ModelContextProtocol

discovery = discover_server("http://127.0.0.1:3010")
client = prepare_manual_client(discovery)
initialize_client!(client)

result = call_tool(client, "add"; arguments=Dict("numbers" => [1, 3, 4]))
terminate_session!(client)

For a stateless client, set MCPClientConfig(protocol_version=ModelContextProtocol.PROTOCOL_VERSION_2026_07_28). The same initialize_client! call then performs server/discover instead of the legacy initialization handshake.

The client rejects result responses whose JSON-RPC ID does not match the request. A rejected initialization response does not establish a session or send an initialized notification.

OAuth

For OAuth-protected MCP servers, use OAuth.jl to acquire a token and attach it before initialization:

using ModelContextProtocol

discovery = discover_server("https://example.com")
client = prepare_manual_client(discovery)

# token is an OAuth.TokenResponse from OAuth.jl.
attach_token!(client, token)
initialize_client!(client)

See the examples/ directory for runnable calculator servers and clients.