Official Swift SDK for the Model Context Protocol (MCP).
The Model Context Protocol (MCP) defines a standardized way for applications to communicate with AI and ML models. This Swift SDK implements both client and server components according to the 2025-11-25 (latest) version of the MCP specification.
- Requirements
- Installation
- Client Usage
- Server Usage
- Transports
- Authentication
- Platform Availability
- Debugging and Logging
- Additional Resources
- Changelog
- License
- Swift 6.1+ (Xcode 16.3+)
A Swift 6.0 package manifest ([email protected]) is also provided for the MCP library,
but CI only tests Swift 6.1 and later.
See the Platform Availability section below for platform-specific requirements.
Add the following to your Package.swift file:
dependencies: [
.package(url: "https://github.com/modelcontextprotocol/swift-sdk.git", from: "0.12.0")
]Then add the dependency to your target:
.target(
name: "YourTarget",
dependencies: [
.product(name: "MCP", package: "swift-sdk")
]
)The client component allows your application to connect to MCP servers.
import MCP
// Initialize the client
let client = Client(name: "MyApp", version: "1.0.0")
// Create a transport and connect
let transport = StdioTransport()
let result = try await client.connect(transport: transport)
// Check server capabilities
if result.capabilities.tools != nil {
// Server supports tools (implicitly including tool calling if the 'tools' capability object is present)
}Note
The Client.connect(transport:) method returns the initialization result.
This return value is discardable,
so you can ignore it if you don't need to check server capabilities.
For communicating with a server running as a local subprocess.
StdioTransport() with no arguments uses the current process's own stdin and stdout,
which is what a server launched by a host application needs.
To talk to a server subprocess from a client, launch it and pass its pipes to the transport:
import Foundation
import MCP
#if canImport(System)
import System
#else
import SystemPackage
#endif
// Launch the server process
let serverInput = Pipe() // the client writes, the server reads
let serverOutput = Pipe() // the server writes, the client reads
let process = Process()
process.executableURL = URL(fileURLWithPath: "/path/to/mcp-server")
process.standardInput = serverInput
process.standardOutput = serverOutput
try process.run()
// Connect over the server's stdin and stdout
let transport = StdioTransport(
input: FileDescriptor(rawValue: serverOutput.fileHandleForReading.fileDescriptor),
output: FileDescriptor(rawValue: serverInput.fileHandleForWriting.fileDescriptor)
)
try await client.connect(transport: transport)For remote server communication:
// Create a streaming HTTP transport
let transport = HTTPClientTransport(
endpoint: URL(string: "http://localhost:8080")!,
streaming: true // Enable Server-Sent Events for real-time updates
)
try await client.connect(transport: transport)Tools represent functions that can be called by the client:
// List available tools
let (tools, cursor) = try await client.listTools()
print("Available tools: \(tools.map { $0.name }.joined(separator: ", "))")
// Call a tool with arguments and get the result
let (content, isError) = try await client.callTool(
name: "image-generator",
arguments: [
"prompt": "A serene mountain landscape at sunset",
"style": "photorealistic",
"width": 1024,
"height": 768
]
)
// Handle tool content
for item in content {
switch item {
case .text(let text, _, _):
print("Generated text: \(text)")
case .image(let data, let mimeType, _, _):
print("Received \(data.count) bytes of base64 image data of type \(mimeType)")
// Decode with Data(base64Encoded: data) to save or display the image
case .audio(_, let mimeType, _, _):
print("Received audio data of type \(mimeType)")
case .resource(let resource, _, _):
print("Received embedded resource: \(resource)")
case .resourceLink(let uri, let name, _, _, let mimeType, _):
print("Resource link: \(name) at \(uri), type: \(mimeType ?? "unknown")")
}
}Resources represent data that can be accessed and potentially subscribed to:
// List available resources
let (resources, nextCursor) = try await client.listResources()
print("Available resources: \(resources.map { $0.uri }.joined(separator: ", "))")
// Read a resource
let contents = try await client.readResource(uri: "resource://example")
print("Resource content: \(contents)")
// Subscribe to resource updates if supported
// (`result` is the initialization result returned by `client.connect(transport:)`)
if result.capabilities.resources?.subscribe == true {
try await client.subscribeToResource(uri: "resource://example")
// Register notification handler
await client.onNotification(ResourceUpdatedNotification.self) { message in
let uri = message.params.uri
print("Resource \(uri) updated with new content")
// Fetch the updated resource content
let updatedContents = try await client.readResource(uri: uri)
print("Updated resource content received")
}
}Prompts represent templated conversation starters:
// List available prompts
let (prompts, nextCursor) = try await client.listPrompts()
print("Available prompts: \(prompts.map { $0.name }.joined(separator: ", "))")
// Get a prompt with arguments
let (description, messages) = try await client.getPrompt(
name: "customer-service",
arguments: [
"customerName": "Alice",
"orderNumber": "ORD-12345",
"issue": "delivery delay"
]
)
// Use the prompt messages in your application
print("Prompt description: \(description ?? "none")")
for message in messages {
if case .text(text: let text) = message.content {
print("\(message.role): \(text)")
}
}Completions allow servers to provide autocompletion suggestions for prompt and resource template arguments as users type:
// Request completions for a prompt argument
let completion = try await client.complete(
promptName: "code_review",
argumentName: "language",
argumentValue: "py"
)
// Display suggestions to the user
for value in completion.values {
print("Suggestion: \(value)")
}
if completion.hasMore == true {
print("More suggestions available (total: \(completion.total ?? 0))")
}You can also provide context with already-resolved arguments:
// First, user selects a language
let languageCompletion = try await client.complete(
promptName: "code_review",
argumentName: "language",
argumentValue: "py"
)
// User selects "python"
// Then get framework suggestions based on the selected language
let frameworkCompletion = try await client.complete(
promptName: "code_review",
argumentName: "framework",
argumentValue: "fla",
context: ["language": "python"]
)
// Returns: ["flask"]Completions work for resource templates as well:
// Get path completions for a resource URI template
let pathCompletion = try await client.complete(
resourceURI: "file:///{path}",
argumentName: "path",
argumentValue: "/usr/"
)
// Returns: ["/usr/bin", "/usr/lib", "/usr/local"]Sampling allows servers to request LLM completions through the client, enabling agentic behaviors while maintaining human-in-the-loop control. Clients register a handler to process incoming sampling requests from servers.
Tip
Sampling requests flow from server to client, not client to server. This enables servers to request AI assistance while clients maintain control over model access and user approval.
The client must declare the sampling capability so that servers know they can send sampling requests:
let client = Client(
name: "MyApp",
version: "1.0.0",
capabilities: .init(sampling: .init())
)Then register a handler for incoming sampling requests:
// Register a sampling handler in the client
await client.withSamplingHandler { parameters in
// Review the sampling request (human-in-the-loop step 1)
print("Server requests completion for: \(parameters.messages)")
// Optionally modify the request based on user input
var messages = parameters.messages
if let systemPrompt = parameters.systemPrompt {
print("System prompt: \(systemPrompt)")
}
// Sample from your LLM (this is where you'd call your AI service)
let completion = try await callYourLLMService(
messages: messages,
maxTokens: parameters.maxTokens,
temperature: parameters.temperature
)
// Review the completion (human-in-the-loop step 2)
print("LLM generated: \(completion)")
// User can approve, modify, or reject the completion here
// Return the result to the server
return CreateSamplingMessage.Result(
model: "your-model-name",
stopReason: .endTurn,
role: .assistant,
content: .text(completion)
)
}Elicitation allows servers to request structured information directly from users through the client. This is useful when servers need user input that wasn't provided in the original request, such as credentials, configuration choices, or approval for sensitive operations.
Tip
Elicitation requests flow from server to client, similar to sampling. Clients must register a handler to respond to elicitation requests from servers.
The client must declare the elicitation capability.
Form mode is enabled by default; include url: .init() to also accept URL-mode requests:
let client = Client(
name: "MyApp",
version: "1.0.0",
capabilities: .init(elicitation: .init(form: .init(), url: .init()))
)Register an elicitation handler to respond to server requests:
// Register an elicitation handler in the client
await client.withElicitationHandler { parameters in
switch parameters {
case .form(let form):
// Display the request to the user
print("Server requests: \(form.message)")
// Inspect the requested schema
let schema = form.requestedSchema
print("Required fields: \(schema.required ?? [])")
print("Schema: \(schema.properties)")
// Present UI to collect user input
let userResponse = presentElicitationUI(form)
// Return the user's response
if userResponse.accepted {
return CreateElicitation.Result(
action: .accept,
content: userResponse.data
)
} else if userResponse.canceled {
return CreateElicitation.Result(action: .cancel)
} else {
return CreateElicitation.Result(action: .decline)
}
case .url(let url):
// Direct the user to an external URL (e.g., for OAuth)
openURL(url.url)
return CreateElicitation.Result(action: .accept)
}
}Common use cases for elicitation:
- Authentication: Request credentials when needed rather than upfront
- Confirmation: Ask for user approval before sensitive operations
- Configuration: Collect preferences or settings during operation
- Missing information: Request additional details not provided initially
Roots define the filesystem boundaries that a client exposes to servers. Servers discover roots by sending a roots/list request to the client; clients notify servers when the list changes.
Tip
To use roots, declare the roots capability when creating the client.
let client = Client(
name: "MyApp",
version: "1.0.0",
capabilities: .init(
roots: .init(listChanged: true)
)
)
// Register a handler for roots/list requests from servers
await client.withRootsHandler {
return [
Root(uri: "file:///Users/user/projects", name: "Projects"),
Root(uri: "file:///Users/user/documents", name: "Documents")
]
}
// Notify connected servers whenever roots change
try await client.notifyRootsChanged()Clients can control server logging levels and receive structured log messages:
// Set the minimum logging level
try await client.setLoggingLevel(.warning)
// Register a handler for log messages from the server
await client.onNotification(LogMessageNotification.self) { message in
let level = message.params.level // LogLevel (debug, info, warning, etc.)
let logger = message.params.logger // Optional logger name
let data = message.params.data // Arbitrary JSON data
// Display log message based on level
switch level {
case .error, .critical, .alert, .emergency:
print("❌ [\(logger ?? "server")] \(data)")
case .warning:
print("⚠️ [\(logger ?? "server")] \(data)")
default:
print("ℹ️ [\(logger ?? "server")] \(data)")
}
}Log levels follow the standard syslog severity levels (RFC 5424):
- debug: Detailed debugging information
- info: General informational messages
- notice: Normal but significant events
- warning: Warning conditions
- error: Error conditions
- critical: Critical conditions
- alert: Action must be taken immediately
- emergency: System is unusable
Handle common client errors:
do {
try await client.connect(transport: transport)
// Success
} catch let error as MCPError {
print("MCP Error: \(error.localizedDescription)")
} catch {
print("Unexpected error: \(error)")
}Either side can cancel an in-progress request and handle incoming cancellations gracefully:
For common operations like tool calls, use the overloaded method that returns RequestContext.
Annotate the type so the compiler picks this overload rather than the one that awaits the result:
// Call a tool and get a context for cancellation
let context: RequestContext<CallTool.Result> = try await client.callTool(
name: "long-running-analysis",
arguments: ["data": largeDataset]
)
// You can cancel the request at any time
try await client.cancelRequest(context.requestID, reason: "User cancelled")
// Await the result (will throw CancellationError if cancelled)
do {
let result = try await context.value
print("Result: \(result.content)")
} catch is CancellationError {
print("Request was cancelled")
}For full control or custom requests, use send() directly:
// Create any request type
let request = CallTool.request(.init(
name: "long-running-analysis",
arguments: ["data": largeDataset]
))
// Send and get a context for cancellation tracking
let context: RequestContext<CallTool.Result> = try await client.send(request)
// Cancel when needed
try await client.cancelRequest(context.requestID, reason: "Timeout")
// Get the result
let result = try await context.value
let content = result.content
let isError = result.isErrorClients can attach a progress token to a request and receive incremental progress updates for long-running operations:
// Call a tool with progress tracking
let progressToken = ProgressToken.unique()
// Register a notification handler to receive progress updates
await client.onNotification(ProgressNotification.self) { message in
let params = message.params
// Filter by your progress token
if params.progressToken == progressToken {
print("Progress: \(params.progress)/\(params.total ?? 0)")
if let message = params.message {
print("Status: \(message)")
}
}
}
// Make the request with the progress token
let (content, isError) = try await client.callTool(
name: "long-running-tool",
arguments: ["input": "value"],
meta: Metadata(progressToken: progressToken)
)Configure client behavior for capability checking:
// Strict configuration - fail fast if a capability is missing
let strictClient = Client(
name: "StrictClient",
version: "1.0.0",
configuration: .strict
)
// With strict configuration, calling a method for an unsupported capability
// will throw an error immediately without sending a request
do {
// This will throw an error if resources.list capability is not available
let resources = try await strictClient.listResources()
} catch let error as MCPError {
print("Capability not available: \(error.localizedDescription)")
}
// Default (non-strict) configuration - attempt the request anyway
let client = Client(
name: "FlexibleClient",
version: "1.0.0",
configuration: .default
)
// With default configuration, the client will attempt the request
// even if the capability wasn't advertised by the server
do {
let resources = try await client.listResources()
} catch let error as MCPError {
// Still handle the error if the server rejects the request
print("Server rejected request: \(error.localizedDescription)")
}Warning
JSON-RPC batching was removed from the MCP specification in protocol revision 2025-06-18.
Only use withBatch with servers that negotiate protocol version 2025-03-26 or earlier.
Send multiple requests in a single JSON-RPC batch.
The batch closure is @Sendable, so collect the returned tasks in an actor rather than a captured var:
/// Collects tasks created inside the batch closure.
actor TaskCollector<Output: Sendable> {
private(set) var tasks: [Task<Output, Swift.Error>] = []
func append(_ task: Task<Output, Swift.Error>) { tasks.append(task) }
}
let toolTasks = TaskCollector<CallTool.Result>()
// Send a batch of requests
try await client.withBatch { batch in
// Add multiple tool calls to the batch
for i in 0..<10 {
let task = try await batch.addRequest(
CallTool.request(.init(name: "square", arguments: ["n": Value(i)]))
)
await toolTasks.append(task)
}
}
// Process results after the batch is sent
let tasks = await toolTasks.tasks
print("Processing \(tasks.count) tool results...")
for (index, task) in tasks.enumerated() {
do {
let result = try await task.value
print("\(index): \(result.content)")
} catch {
print("\(index) failed: \(error)")
}
}You can also batch different types of requests:
let pingTasks = TaskCollector<Ping.Result>()
let promptTasks = TaskCollector<GetPrompt.Result>()
// Send a batch with different request types
try await client.withBatch { batch in
await pingTasks.append(try await batch.addRequest(Ping.request()))
await promptTasks.append(
try await batch.addRequest(GetPrompt.request(.init(name: "greeting")))
)
}
// Process individual results
do {
for task in await pingTasks.tasks {
_ = try await task.value
print("Ping successful")
}
for task in await promptTasks.tasks {
let promptResult = try await task.value
print("Prompt: \(promptResult.description ?? "None")")
}
} catch {
print("Error processing batch results: \(error)")
}Note
Server still accepts batch requests from clients for backward compatibility with earlier protocol versions.
The server component allows your application to host model capabilities and respond to client requests.
import MCP
// Create a server with given capabilities
let server = Server(
name: "MyModelServer",
version: "1.0.0",
capabilities: .init(
completions: .init(),
logging: .init(),
prompts: .init(listChanged: true),
resources: .init(subscribe: true, listChanged: true),
tools: .init(listChanged: true)
)
)
// Create transport and start server
let transport = StdioTransport()
try await server.start(transport: transport)
// Now register handlers for the capabilities you've enabledRegister tool handlers to respond to client tool calls:
// 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([
"type": "object",
"properties": .object([
"location": .object([
"type": "string",
"description": "City name or coordinates"
]),
"units": .object([
"type": "string",
"description": "Units of measurement, e.g., metric, imperial"
])
])
])
),
Tool(
name: "calculator",
description: "Perform calculations",
inputSchema: .object([
"type": "object",
"properties": .object([
"expression": .object([
"type": "string",
"description": "Mathematical expression to evaluate"
])
])
])
)
]
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"
let units = params.arguments?["units"]?.stringValue ?? "metric"
let weatherData = getWeatherData(location: location, units: units) // Your implementation
return .init(
content: [
.text(
text: "Weather for \(location): \(weatherData.temperature)°, \(weatherData.conditions)",
annotations: nil,
_meta: nil
)
],
isError: false
)
case "calculator":
if let expression = params.arguments?["expression"]?.stringValue {
let result = evaluateExpression(expression) // Your implementation
return .init(content: [.text(text: "\(result)", annotations: nil, _meta: nil)], isError: false)
} else {
return .init(content: [.text(text: "Missing expression parameter", annotations: nil, _meta: nil)], isError: true)
}
default:
return .init(content: [.text(text: "Unknown tool", annotations: nil, _meta: nil)], isError: true)
}
}Implement resource handlers for data access:
// Register a resource list handler
await server.withMethodHandler(ListResources.self) { params in
let resources = [
Resource(
name: "Knowledge Base Articles",
uri: "resource://knowledge-base/articles",
description: "Collection of support articles and documentation"
),
Resource(
name: "System Status",
uri: "resource://system/status",
description: "Current system operational status"
)
]
return .init(resources: resources, nextCursor: nil)
}
// Register a resource read handler
await server.withMethodHandler(ReadResource.self) { params in
switch params.uri {
case "resource://knowledge-base/articles":
return .init(contents: [Resource.Content.text("# Knowledge Base\n\nThis is the content of the knowledge base...", uri: params.uri)])
case "resource://system/status":
let status = getCurrentSystemStatus() // Your implementation
let statusJson = """
{
"status": "\(status.overall)",
"components": {
"database": "\(status.database)",
"api": "\(status.api)",
"model": "\(status.model)"
},
"lastUpdated": "\(status.timestamp)"
}
"""
return .init(contents: [Resource.Content.text(statusJson, uri: params.uri, mimeType: "application/json")])
default:
throw MCPError.invalidParams("Unknown resource URI: \(params.uri)")
}
}
// Register a resource subscribe handler
await server.withMethodHandler(ResourceSubscribe.self) { params in
// Store subscription for later notifications.
// Client identity for multi-client scenarios needs to be managed by the server application,
// potentially using information from the initialize handshake if the server handles one client post-init.
// addSubscription(clientID: /* some_client_identifier */, uri: params.uri)
print("Client subscribed to \(params.uri). Server needs to implement logic to track this subscription.")
return .init()
}Implement prompt handlers:
// 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),
.init(name: "company", description: "Company name", required: true),
.init(name: "interviewee", description: "Candidate name")
]
),
Prompt(
name: "customer-support",
description: "Customer support conversation starter",
arguments: [
.init(name: "issue", description: "Customer issue", required: true),
.init(name: "product", description: "Product name", 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 position = params.arguments?["position"] ?? "Software Engineer"
let company = params.arguments?["company"] ?? "Acme Corp"
let interviewee = params.arguments?["interviewee"] ?? "Candidate"
let description = "Job interview for \(position) position at \(company)"
let messages: [Prompt.Message] = [
.user(.text(text: "You are an interviewer for the \(position) position at \(company).")),
.user(.text(text: "Hello, I'm \(interviewee) and I'm here for the \(position) interview.")),
.assistant(.text(text: "Hi \(interviewee), welcome to \(company)! I'd like to start by asking about your background and experience."))
]
return .init(description: description, messages: messages)
case "customer-support":
let issue = params.arguments?["issue"] ?? "an issue"
let product = params.arguments?["product"] ?? "the product"
return .init(
description: "Customer support for \(product)",
messages: [.user(.text(text: "I need help with \(issue) in \(product)."))]
)
default:
throw MCPError.invalidParams("Unknown prompt name: \(params.name)")
}
}Servers can provide autocompletion suggestions for prompt and resource template arguments:
// Enable completions capability
let server = Server(
name: "MyServer",
version: "1.0.0",
capabilities: .init(
completions: .init(),
prompts: .init(listChanged: true)
)
)
// Register a completion handler
await server.withMethodHandler(Complete.self) { params in
// Get the argument being completed
let argumentName = params.argument.name
let currentValue = params.argument.value
// Check which prompt or resource is being completed
switch params.ref {
case .prompt(let promptRef):
// Provide completions for a prompt argument
if promptRef.name == "code_review" && argumentName == "language" {
// Simple prefix matching
let allLanguages = ["python", "perl", "php", "javascript", "java", "swift"]
let matches = allLanguages.filter { $0.hasPrefix(currentValue.lowercased()) }
return .init(
completion: .init(
values: Array(matches.prefix(100)), // Max 100 items
total: matches.count,
hasMore: matches.count > 100
)
)
}
case .resource(let resourceRef):
// Provide completions for a resource template argument
if resourceRef.uri == "file:///{path}" && argumentName == "path" {
// Return directory suggestions
let suggestions = try getDirectoryCompletions(for: currentValue)
return .init(
completion: .init(
values: suggestions,
total: suggestions.count,
hasMore: false
)
)
}
}
// No completions available
return .init(completion: .init(values: [], total: 0, hasMore: false))
}You can also use context from already-resolved arguments:
await server.withMethodHandler(Complete.self) { params in
// Access context from previous argument completions
if let context = params.context,
let language = context.arguments["language"] {
// Provide framework suggestions based on selected language
if language == "python" {
let frameworks = ["flask", "django", "fastapi", "tornado"]
let matches = frameworks.filter {
$0.hasPrefix(params.argument.value.lowercased())
}
return .init(
completion: .init(values: matches, total: matches.count, hasMore: false)
)
}
}
return .init(completion: .init(values: [], total: 0, hasMore: false))
}Servers can request LLM completions from clients through sampling. This enables agentic behaviors where servers can ask for AI assistance while maintaining human oversight.
Sampling is a client capability: the server doesn't declare anything,
but it can only send sampling requests to clients that declared sampling during initialization.
With configuration: .strict, requestSampling throws if the client didn't declare it.
let server = Server(
name: "MyModelServer",
version: "1.0.0",
capabilities: .init(
tools: .init(listChanged: true)
)
)
// Request sampling from the connected client
do {
let result = try await server.requestSampling(
messages: [
.user("Analyze this data and suggest next steps")
],
systemPrompt: "You are a helpful data analyst",
temperature: 0.7,
maxTokens: 150
)
// Use the LLM completion in your server logic
print("LLM suggested: \(result.content)")
} catch {
print("Sampling request failed: \(error)")
}Sampling enables powerful agentic workflows:
- Decision-making: Ask the LLM to choose between options
- Content generation: Request drafts for user approval
- Data analysis: Get AI insights on complex data
- Multi-step reasoning: Chain AI completions with tool calls
Servers can request information from users through elicitation:
// Ask the user to provide some additional information
let schema = Elicitation.RequestSchema(
title: "Additional Information Required",
description: "Please provide the following details to continue",
properties: [
"name": .object([
"type": .string("string"),
"description": .string("Your full name")
]),
"confirmed": .object([
"type": .string("boolean"),
"description": .string("Do you confirm the provided information?")
])
],
required: ["name", "confirmed"]
)
let result = try await server.requestElicitation(
message: "Some details are needed before proceeding",
requestedSchema: schema
)
switch result.action {
case .accept:
if let content = result.content {
let name = content["name"]?.stringValue
let confirmed = content["confirmed"]?.boolValue
// Use the collected data...
}
case .decline:
throw MCPError.invalidRequest("User declined to provide information")
case .cancel:
throw MCPError.invalidRequest("Operation canceled by user")
}For URL-based elicitation (e.g., OAuth flows), use the URL overload:
let result = try await server.requestElicitation(
message: "Please sign in to continue",
url: "https://example.com/oauth/authorize?client_id=...",
elicitationId: UUID().uuidString
)Servers can request the list of filesystem roots that the client has exposed:
// Request roots from the connected client
// (requires the client to declare the roots capability)
let roots = try await server.listRoots()
for root in roots {
print("Root: \(root.name ?? root.uri) at \(root.uri)")
}
// React to root list changes
await server.onNotification(RootsListChangedNotification.self) { _ in
let updatedRoots = try await server.listRoots()
print("Roots updated: \(updatedRoots.map { $0.uri })")
}Servers can send structured log messages to clients:
// Enable logging capability
let server = Server(
name: "MyServer",
version: "1.0.0",
capabilities: .init(
logging: .init(),
tools: .init(listChanged: true)
)
)
// Send log messages at different severity levels
try await server.log(
level: .info,
logger: "database",
data: Value.object([
"message": .string("Database connected successfully"),
"host": .string("localhost"),
"port": .int(5432)
])
)
try await server.log(
level: .error,
logger: "api",
data: Value.object([
"message": .string("Request failed"),
"statusCode": .int(500),
"error": .string("Internal server error")
])
)
// You can also use codable types directly
struct ErrorLog: Codable {
let message: String
let code: Int
let timestamp: String
}
let errorLog = ErrorLog(
message: "Operation failed",
code: 500,
timestamp: ISO8601DateFormatter().string(from: Date())
)
try await server.log(level: .error, logger: "operations", data: errorLog)Clients can control which log levels they receive:
// Register a handler for client's logging level preferences
await server.withMethodHandler(SetLoggingLevel.self) { params in
let minimumLevel = params.level
// Store the client's preference and filter log messages accordingly
// (Implementation depends on your server architecture)
storeLogLevel(minimumLevel)
return Empty()
}Servers can send incremental progress notifications during long-running tool calls by reading the progressToken from the request metadata and sending ProgressNotification messages:
await server.withMethodHandler(CallTool.self) { params in
// Read the progress token from request metadata
guard let token = params._meta?.progressToken else {
// No progress token provided — run without reporting progress
return .init(content: [.text(text: "Done", annotations: nil, _meta: nil)], isError: false)
}
// Report initial progress
let started = ProgressNotification.message(
.init(progressToken: token, progress: 0, total: 100)
)
try await server.notify(started)
// ... do work ...
// Report intermediate progress
let halfway = ProgressNotification.message(
.init(progressToken: token, progress: 50, total: 100, message: "Halfway there")
)
try await server.notify(halfway)
// ... do more work ...
// Report completion
let done = ProgressNotification.message(
.init(progressToken: token, progress: 100, total: 100, message: "Complete")
)
try await server.notify(done)
return .init(content: [.text(text: "Done", annotations: nil, _meta: nil)], isError: false)
}Control client connections with an initialize hook:
// Start the server with an initialize hook
try await server.start(transport: transport) { clientInfo, clientCapabilities in
// Validate client info
guard clientInfo.name != "BlockedClient" else {
throw MCPError.invalidRequest("This client is not allowed")
}
// You can also inspect client capabilities
if clientCapabilities.sampling == nil {
print("Client does not support sampling")
}
// Perform any server-side setup based on client info
print("Client \(clientInfo.name) v\(clientInfo.version) connected")
// If the hook completes without throwing, initialization succeeds
}When a server is connected over StatefulHTTPServerTransport or StatelessHTTPServerTransport,
method handlers can observe the originating HTTP request (headers, body, path, method) via
Server.currentHandlerContext — a task-local set automatically before each handler runs:
await server.withMethodHandler(CallTool.self) { params in
let httpRequest = Server.currentHandlerContext?.httpContext
let authHeader = httpRequest?.header("Authorization") // case-insensitive lookup
// …use the header to scope the response, audit, etc.
return .init(content: [.text(text: "ok", annotations: nil, _meta: nil)], isError: false)
}httpContext is nil for transports that don't carry HTTP context (e.g. StdioTransport,
InMemoryTransport) and for handlers reached off the dispatch path.
Task-locals are not inherited by Task.detached. If you spawn a detached task from a handler,
capture the context up front:
let ctx = Server.currentHandlerContext
Task.detached { await doWork(with: ctx?.httpContext) }Custom HTTP transports can opt in by conforming to HTTPContextProviding and returning the
HTTPRequest for a given JSON-RPC id while it is in flight.
We recommend using Swift Service Lifecycle for managing startup and shutdown of services.
First, add the dependency to your Package.swift:
.package(url: "https://github.com/swift-server/swift-service-lifecycle.git", from: "2.3.0"),Then implement the MCP server as a Service:
import MCP
import ServiceLifecycle
import Logging
struct MCPService: Service {
let server: Server
let transport: any Transport
func run() async throws {
// Start the server
try await server.start(transport: transport)
// Run until the transport closes, or stop the server on graceful shutdown
await withGracefulShutdownHandler {
await server.waitUntilCompleted()
} onGracefulShutdown: {
Task { await server.stop() }
}
}
}Then use it in your application:
import MCP
import ServiceLifecycle
import Logging
let logger = Logger(label: "com.example.mcp-server")
// Create the MCP server
let server = Server(
name: "MyModelServer",
version: "1.0.0",
capabilities: .init(
prompts: .init(listChanged: true),
resources: .init(subscribe: true, listChanged: true),
tools: .init(listChanged: true)
)
)
// Add handlers directly to the server
await server.withMethodHandler(ListTools.self) { _ in
// Your implementation
return .init(tools: [
Tool(
name: "example",
description: "An example tool",
inputSchema: .object(["type": "object"])
)
])
}
await server.withMethodHandler(CallTool.self) { params in
// Your implementation
return .init(content: [.text(text: "Tool result", annotations: nil, _meta: nil)], isError: false)
}
// Create MCP service and other services
let transport = StdioTransport(logger: logger)
let mcpService = MCPService(server: server, transport: transport)
let databaseService = DatabaseService() // Your other services
// Create service group with signal handling
let serviceGroup = ServiceGroup(
services: [mcpService, databaseService],
configuration: .init(
gracefulShutdownSignals: [.sigterm, .sigint]
),
logger: logger
)
// Run the service group - this blocks until shutdown
try await serviceGroup.run()This approach has several benefits:
- Signal handling: Automatically traps SIGINT, SIGTERM and triggers graceful shutdown
- Graceful shutdown: Properly shuts down your MCP server and other services
- Timeout-based shutdown: Configurable shutdown timeouts to prevent hanging processes
- Advanced service management: ServiceLifecycle also supports service dependencies, conditional services, and other useful features.
MCP's transport layer handles communication between clients and servers. The Swift SDK provides multiple built-in transports:
| Transport | Description | Platforms | Best for |
|---|---|---|---|
StdioTransport |
Implements stdio transport using standard input/output streams | Apple platforms, Linux (glibc and musl) | Local subprocesses, CLI tools |
HTTPClientTransport |
Implements Streamable HTTP transport using Foundation's URL Loading System | All platforms with Foundation (SSE streaming on Apple platforms only; Linux uses request/response) | Remote servers, web applications |
StatelessHTTPServerTransport |
HTTP server transport with simple request-response semantics; no session management or SSE streaming, so server-to-client requests and notifications aren't delivered | All platforms with Foundation | Simple HTTP servers, serverless/edge functions |
StatefulHTTPServerTransport |
HTTP server transport with full session management and SSE streaming for server-initiated messages | All platforms with Foundation | Full-featured HTTP servers, streaming notifications |
InMemoryTransport |
Custom in-memory transport for direct communication within the same process | All platforms | Testing, debugging, same-process client-server communication |
NetworkTransport |
Custom (non-standard) transport using Apple's Network framework for TCP/UDP connections, with heartbeats and automatic reconnection enabled by default; both peers should use NetworkTransport |
Apple platforms only | Low-level networking, custom protocols |
You can implement a custom transport by conforming to the Transport protocol:
import MCP
import Foundation
public actor MyCustomTransport: Transport {
public nonisolated let logger: Logger
private var isConnected = false
private let messageStream: AsyncThrowingStream<Data, any Swift.Error>
private let messageContinuation: AsyncThrowingStream<Data, any Swift.Error>.Continuation
public init(logger: Logger? = nil) {
self.logger = logger ?? Logger(label: "my.custom.transport")
var continuation: AsyncThrowingStream<Data, any Swift.Error>.Continuation!
self.messageStream = AsyncThrowingStream { continuation = $0 }
self.messageContinuation = continuation
}
public func connect() async throws {
// Implement your connection logic
isConnected = true
}
public func disconnect() async {
// Implement your disconnection logic
isConnected = false
messageContinuation.finish()
}
public func send(_ data: Data) async throws {
// Implement your message sending logic
}
public func receive() -> AsyncThrowingStream<Data, any Swift.Error> {
return messageStream
}
}HTTPClientTransport supports OAuth 2.1 Bearer token authorization per the
MCP authorization specification.
When a server returns 401 Unauthorized or 403 Forbidden, the transport automatically:
- Discovers Protected Resource Metadata (RFC 9728) at
/.well-known/oauth-protected-resource - Discovers Authorization Server Metadata (RFC 8414 / OIDC Discovery 1.0)
- For a client configured with
.none(clientID:), uses the client ID as a Client ID Metadata Document when it's an HTTPS URL and the authorization server supports them; otherwise registers the client dynamically (RFC 7591) if needed - Acquires a Bearer token using the configured grant flow (PKCE enforced),
refreshing tokens with a
refresh_tokengrant when possible - Retries the original request with the token attached,
and requests additional scopes when a server responds with
403 insufficient_scope
Authorization is opt-in and disabled by default.
Pass an OAuthAuthorizer to HTTPClientTransport(authorizer:) to enable it.
Machine-to-machine authentication using a pre-shared client secret:
let config = OAuthConfiguration(
grantType: .clientCredentials,
authentication: .clientSecretBasic(clientID: "my-app", clientSecret: "s3cr3t")
)
let authorizer = OAuthAuthorizer(configuration: config)
let transport = HTTPClientTransport(
endpoint: URL(string: "https://api.example.com/mcp")!,
authorizer: authorizer
)
let client = Client(name: "MyClient", version: "1.0.0")
try await client.connect(transport: transport)Interactive, browser-based authentication with PKCE.
Implement OAuthAuthorizationDelegate to open the authorization URL and capture the redirect:
struct MyAuthDelegate: OAuthAuthorizationDelegate {
func presentAuthorizationURL(_ url: URL) async throws -> URL {
// Open the URL in a browser/webview and wait for the callback redirect URI.
// The returned URL must include the authorization code and state parameters.
return try await openBrowserAndWaitForCallback(url)
}
}
let config = OAuthConfiguration(
grantType: .authorizationCode,
authentication: .none(clientID: "my-app"),
authorizationDelegate: MyAuthDelegate()
)
let authorizer = OAuthAuthorizer(configuration: config)
let transport = HTTPClientTransport(
endpoint: URL(string: "https://api.example.com/mcp")!,
authorizer: authorizer
)Important
By default, authorizationRedirectURI is a loopback URL on a random port that isn't reserved in advance,
so another local process could claim the port first.
In production, pass authorizationRedirectURI: with a fixed port or a custom URL scheme.
Supply an externally acquired token (e.g., from a system credential store) via accessTokenProvider.
The SDK calls this closure after discovery completes. Return nil to fall back to the configured grant flow:
let config = OAuthConfiguration(
grantType: .clientCredentials,
authentication: .none(clientID: "my-app"),
accessTokenProvider: { context, session in
// context contains the discovered resource URI, token endpoint, scopes, etc.
return try await KeychainTokenStore.shared.loadToken(for: context.resource)
}
)By default, tokens are stored in memory and lost when the process exits.
To persist tokens across sessions, implement TokenStorage and pass it to OAuthAuthorizer:
final class KeychainTokenStorage: TokenStorage {
func save(_ token: OAuthAccessToken) {
// Encode and store token.value in the system Keychain
}
func load() -> OAuthAccessToken? {
// Load and decode token from the Keychain
return nil
}
func clear() {
// Delete from the Keychain
}
}
let authorizer = OAuthAuthorizer(
configuration: config,
tokenStorage: KeychainTokenStorage()
)Authenticate to the token endpoint using an asymmetric key (RFC 7523). The SDK provides a built-in ES256 helper for P-256 keys:
let config = OAuthConfiguration(
grantType: .clientCredentials,
authentication: .privateKeyJWT(
clientID: "my-app",
assertionFactory: { tokenEndpoint, clientID in
try OAuthConfiguration.makePrivateKeyJWTAssertion(
clientID: clientID,
tokenEndpoint: tokenEndpoint,
privateKeyPEM: myEC256PrivateKeyPEM // PEM-encoded P-256 private key
)
}
)
)Skip automatic discovery by providing explicit endpoint URLs. Useful when the server does not publish well-known metadata documents:
let config = OAuthConfiguration(
grantType: .clientCredentials,
authentication: .clientSecretBasic(clientID: "app", clientSecret: "secret"),
endpointOverrides: OAuthConfiguration.EndpointOverrides(
tokenEndpoint: URL(string: "https://auth.example.com/oauth/token")!
)
)Per the MCP authorization specification, servers MUST serve Protected Resource Metadata
at /.well-known/oauth-protected-resource so clients can discover authorization server endpoints.
Use ProtectedResourceMetadataValidator as the first validator in your pipeline so that
unauthenticated discovery requests are handled before the bearer token check:
let metadata = OAuthProtectedResourceServerMetadata(
resource: "https://api.example.com",
authorizationServers: [URL(string: "https://auth.example.com")!],
scopesSupported: ["read", "write"]
)
let metadataValidator = ProtectedResourceMetadataValidator(metadata: metadata)Use BearerTokenValidator to authenticate incoming requests.
Your tokenValidator closure MUST verify the token's aud claim to prevent
token substitution attacks where a token intended for another resource is replayed against your server:
let resourceIdentifier = URL(string: "https://api.example.com")!
let bearerValidator = BearerTokenValidator(
resourceMetadataURL: URL(string: "https://api.example.com/.well-known/oauth-protected-resource")!,
resourceIdentifier: resourceIdentifier,
tokenValidator: { token, request, context in
guard let claims = try? verifyAndDecodeJWT(token) else {
return .invalidToken(errorDescription: "Token verification failed")
}
// Pass audience and expiry to BearerTokenInfo; the SDK validates the
// audience claim against resourceIdentifier automatically.
return .valid(BearerTokenInfo(
audience: claims.audience,
expiresAt: claims.expiresAt
))
}
)
let pipeline = StandardValidationPipeline(validators: [
OriginValidator( // DNS rebinding protection
allowedHosts: ["api.example.com"],
allowedOrigins: ["https://api.example.com"]
),
metadataValidator, // serves /.well-known/oauth-protected-resource unauthenticated
bearerValidator, // validates Bearer tokens on all other requests
AcceptHeaderValidator(mode: .sseRequired),
ContentTypeValidator(),
ProtocolVersionValidator(),
SessionValidator(),
])
let transport = StatefulHTTPServerTransport(validationPipeline: pipeline)A custom pipeline replaces the transport's default one, so keep the default validators in it.
In particular, OriginValidator provides DNS rebinding protection;
the default pipeline only allows localhost hosts and origins.
The Swift SDK has the following platform requirements:
| Platform | Minimum Version |
|---|---|
| macOS | 13.0+ |
| iOS / Mac Catalyst | 16.0+ |
| watchOS | 9.0+ |
| tvOS | 16.0+ |
| visionOS | 1.0+ |
| Linux | Distributions with glibc or musl, including Ubuntu, Debian, Fedora, and Alpine Linux |
While the core library works on any platform supporting Swift 6 (including Linux), running a client or server requires a compatible transport.
On Linux, some features need frameworks that are only available on Apple platforms:
HTTPClientTransportdoesn't support SSE streaming and uses request/response instead.- The OAuth authorization code flow throws
pkceS256Unavailable, because PKCE S256 requires CryptoKit. private_key_jwtclient assertions throwcryptographyUnavailable.NetworkTransportrequires the Network framework.
Enable logging to help troubleshoot issues.
Client and Server log through their transport's logger, so pass the logger to the transport:
import Logging
import MCP
// Configure logging. Log to standard error: for stdio servers,
// standard output carries MCP messages and must not contain anything else.
LoggingSystem.bootstrap { label in
var handler = StreamLogHandler.standardError(label: label)
handler.logLevel = .debug
return handler
}
// Create logger
let logger = Logger(label: "com.example.mcp")
// Pass it to the transport. Each client or server needs its own transport.
// In a client:
let client = Client(name: "MyApp", version: "1.0.0")
try await client.connect(transport: StdioTransport(logger: logger))
// Or, in a server:
let server = Server(name: "MyServer", version: "1.0.0")
try await server.start(transport: StdioTransport(logger: logger))This project follows Semantic Versioning. For pre-1.0 releases, minor version increments (0.X.0) may contain breaking changes.
For details about changes in each release, see the GitHub Releases page.
This project is licensed under Apache 2.0 for new contributions, with existing code under MIT. See the LICENSE file for details.