MCP Swift SDK

Sampling and Elicitation are flows where the server requests information from the client.

• Sampling: The server requests an LLM completion. Use withSamplingHandler to intercept the request, potentially review it (human-in-the-loop), call your own LLM service, and return a CreateSamplingMessage.Result.
• Elicitation: The server requests structured information (like credentials or user confirmation) via a form or a URL. Use withElicitationHandler to present a UI to the user and return a CreateElicitation.Result (accept, cancel, or decline).

// Sampling Handler
await client.withSamplingHandler { parameters in
    let completion = try await callYourLLMService(messages: parameters.messages)
    return CreateSamplingMessage.Result(
        model: "my-model",
        stopReason: .endTurn,
        role: .assistant,
        content: .text(completion)
    )
}

// Elicitation Handler
await client.withElicitationHandler { parameters in
    switch parameters {
    case .form(let form):
        let userResponse = presentElicitationUI(form)
        return CreateElicitation.Result(action: .accept, content: userResponse.data)
    case .url(let url):
        openURL(url.url)
        return CreateElicitation.Result(action: .accept)
    }
}

Tools allow clients to execute specific functions. You must register two types of handlers:

1. ListTools: Returns an array of Tool objects defining the tool's name, description, and inputSchema (using JSON Schema-like structure).
2. CallTool: Executes the logic when a tool is called. It receives params containing the tool name and arguments. You should return a result containing content (e.g., .text) and an isError flag.

// Register a tool list handler
await server.withMethodHandler(ListTools.self) { _ in
    let tools = [
        Tool(
            name: "weather",
            description: "Get current weather for a location",
            inputSchema: .object([
                "properties": .object([
                    "location": .string("City name or coordinates"),
                    "units": .string("Units of measurement, e.g., metric, imperial")
                ])
            ])
        )
    ]
    return .init(tools: tools)
}

// Register a tool call handler
await server.withMethodHandler(CallTool.self) { params in
    switch params.name {
    case "weather":
        let location = params.arguments?["location"]?.stringValue ?? "Unknown"
        // ... implementation ...
        return .init(
            content: [.text("Weather for \(location): ...")],
            isError: false
        )
    default:
        return .init(content: [.text("Unknown tool")], isError: true)
    }
}

Servers can provide autocompletion for prompt and resource template arguments using the Complete handler. The handler receives params containing the argument being completed and a ref (either .prompt or .resource). You can also access params.context to provide suggestions based on previously resolved arguments in the same session.

// Register a completion handler
await server.withMethodHandler(Complete.self) { params in
    switch params.ref {
    case .prompt(let promptRef):
        if promptRef.name == "code_review" && params.argument.name == "language" {
            let matches = ["python", "swift"].filter { $0.hasPrefix(params.argument.value.lowercased()) }
            return .init(completion: .init(values: matches, total: matches.count, hasMore: false))
        }
    case .resource(let resourceRef):
        // Handle resource template completions
        break
    }
    return .init(completion: .init(values: [], total: 0, hasMore: false))
}

Prompts are reusable conversation starters. Implement:

• ListPrompts: Returns a list of Prompt objects, including their name, description, and required/optional arguments.
• GetPrompt: Returns the specific Prompt details, including a description and a sequence of messages (user or assistant) to seed the conversation.

// Register a prompt list handler
await server.withMethodHandler(ListPrompts.self) { params in
    let prompts = [
        Prompt(
            name: "interview",
            description: "Job interview conversation starter",
            arguments: [
                .init(name: "position", description: "Job position", required: true)
            ]
        )
    ]
    return .init(prompts: prompts, nextCursor: nil)
}

// Register a prompt get handler
await server.withMethodHandler(GetPrompt.self) { params in
    switch params.name {
    case "interview":
        let messages: [Prompt.Message] = [
            .user(.text(text: "You are an interviewer...")),
            .assistant(.text(text: "Hi, welcome!"))
        ]
        return .init(description: "Interview prompt", messages: messages)
    default:
        throw MCPError.invalidParams("Unknown prompt name: \(params.name)")
    }
}