How to Build an MCP Server in Swift (Swift SDK 0.12, 2026)

You can build an MCP server in Swift with the official Swift SDK, added through Swift Package Manager as the MCP product of modelcontextprotocol/swift-sdk. You create a Server, register handlers for ListTools and CallTool, and start it on a transport such as StdioTransport. It runs on Apple platforms and on Linux.

This guide builds a small stdio server, adds a tool, tests it with MCP Inspector and connects it to Claude Desktop. It also covers the HTTP transports, and what the SDK's Tier 3 status and protocol version mean before you depend on it.

Checked against: the Swift SDK README on main and at the 0.12.1 tag, plus the SDK source for Server, Tool and Value at 0.12.1, on 2 November 2026. eSEOspace did not compile or run this Swift code; the machine used had Swift 5.10, and the SDK requires Swift 6.0 or later.

Prerequisites

• Swift 6.0 or later. The README lists "Swift 6.0+ (Xcode 16+)."
• macOS 13.0+, or Linux with glibc or musl (Ubuntu, Debian, Fedora and Alpine are named). iOS 16+, watchOS 9+, tvOS 16+ and visionOS 1+ are supported for the library too.
• Node.js, to run MCP Inspector.
• A client such as Claude Desktop.

If you are new to MCP servers, read how to build your first MCP server for the concepts first.

Step 1: Create the package

Create an executable package with swift package init --type executable. Then add the SDK in Package.swift. The dependency and product lines below come from the README; the version is the current release:

// swift-tools-version: 6.0
import PackageDescription

let package = Package(
    name: "Bookshop",
    platforms: [.macOS(.v13)],
    dependencies: [
        .package(url: "https://github.com/modelcontextprotocol/swift-sdk.git", from: "0.12.1")
    ],
    targets: [
        .executableTarget(
            name: "Bookshop",
            dependencies: [
                .product(name: "MCP", package: "swift-sdk")
            ]
        )
    ]
)

The README's snippet still says from: "0.11.0". That resolves to the newest 0.x release below 1.0 too, but pinning 0.12.1 makes the minimum explicit. Because the SDK is pre-1.0 and Tier 3, read the release notes before you move to a new minor version.

Step 2: Write a stdio server with one tool

This bookshop server uses the Server, withMethodHandler and StdioTransport APIs from the README:

import MCP

let catalog = ["Dune": "Frank Herbert", "Neuromancer": "William Gibson"]

let server = Server(
    name: "bookshop",
    version: "1.0.0",
    capabilities: .init(tools: .init(listChanged: false))
)

await server.withMethodHandler(ListTools.self) { _ in
    .init(tools: [
        Tool(
            name: "search_books",
            description: "Search the catalog by title or author. Returns matching titles.",
            inputSchema: .object([
                "type": "object",
                "properties": .object([
                    "query": .object([
                        "type": "string",
                        "description": "Part of a title or author name"
                    ])
                ]),
                "required": .array(["query"])
            ])
        )
    ])
}

await server.withMethodHandler(CallTool.self) { params in
    switch params.name {
    case "search_books":
        guard let query = params.arguments?["query"]?.stringValue?.lowercased() else {
            return .init(content: [.text("The 'query' argument is required.")], isError: true)
        }
        let hits = catalog
            .filter { $0.key.lowercased().contains(query) || $0.value.lowercased().contains(query) }
            .map { $0.key }
        return .init(content: [.text(hits.isEmpty ? "No matches." : hits.joined(separator: "\n"))], isError: false)
    default:
        return .init(content: [.text("Unknown tool: \(params.name)")], isError: true)
    }
}

let transport = StdioTransport()
try await server.start(transport: transport)
await server.waitUntilCompleted()

What each part does:

• Server(name:version:capabilities:) creates the server and declares the tools capability.
• The ListTools handler answers tools/list. Each Tool carries a name, a description and an inputSchema written as a JSON Schema Value.
• The CallTool handler answers tools/call. You switch on params.name and read arguments with accessors such as stringValue.
• .init(content:isError:) builds the result. isError: true tells the model the call failed, in words it can act on.
• StdioTransport() reads stdin and writes stdout. start(transport:) connects it.
• waitUntilCompleted() is a public method on Server in the 0.12.1 source. It waits for the server's message loop, which keeps the process alive until the client disconnects.

The README's Basic Server Setup calls start first and registers handlers after it. Registering handlers first, as above, means no request can arrive before a handler exists.

Step 3: Add more tools

Add each new tool to the array in the ListTools handler and add a matching case to the CallTool switch. Keep the two in sync; a tool that is listed but has no case returns your "Unknown tool" error.

Keep each tool narrow, with plain names and argument descriptions. The model only sees the name, the description and the schema.

If your tool list can change while the server runs, set listChanged: true and send a list-changed notification when it does. For a fixed list, leave it false.

Step 4: Test with MCP Inspector

Build with swift build -c release, then point the MCP Inspector CLI at the binary:

npx @modelcontextprotocol/inspector --cli .build/release/Bookshop \
  --protocol-era legacy --method tools/list

npx @modelcontextprotocol/inspector --cli .build/release/Bookshop \
  --protocol-era legacy --method tools/call \
  --tool-name search_books --tool-arg query=dune

--protocol-era legacy makes the Inspector use the initialize handshake that this SDK speaks. Running npx @modelcontextprotocol/inspector with no flags opens the web UI. Our lesson on testing with MCP Inspector walks through both.

Step 5: Connect it to Claude Desktop

Add the built binary under mcpServers in claude_desktop_config.json. On macOS the file is ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "bookshop": {
      "command": "/ABSOLUTE/PATH/TO/Bookshop/.build/release/Bookshop"
    }
  }
}

Restart Claude Desktop. Our MCP config generator writes the same entry for other clients.

Transports

The README lists these transports:

Both HTTP server transports exist in the 0.12.1 source. The README describes the stateless one as suited to "serverless/edge functions." Handlers on either HTTP transport can read the original request, including headers such as Authorization, through Server.currentHandlerContext.

For long-running services, the README shows wrapping the server in an MCPService run by swift-service-lifecycle, which traps SIGINT and SIGTERM and shuts down cleanly. For a remote deployment walk-through, see our lesson on deploying a remote MCP server.

Common pitfalls

• Logging to stdout. The README's debugging example uses StreamLogHandler.standardOutput. That is fine for a client, but in a stdio server any stdout output corrupts the JSON-RPC stream. Use StreamLogHandler.standardError instead.
• Swift 5.x toolchains. The SDK requires Swift 6.0+. Older Xcode or Linux toolchains will fail to resolve or build it.
• Expecting 2026-07-28. The 0.12.1 source lists 2025-11-25 as the newest supported version. A client that only speaks 2026-07-28 will not negotiate with it.
• Old schema examples. The 0.12.1 README showed tool properties as plain strings, such as "location": .string("City name"), which is not valid JSON Schema. The current README nests type and description objects, as in the code above.
• Forgetting to keep the process alive. Without waitUntilCompleted() or a service group, a top-level script can exit right after start.
• Relative paths in client config. Desktop clients start your binary from their own working directory.

Next step

Continue with the free MCP course to add resources, prompts and OAuth. If you want a Swift or Apple-platform MCP integration built for your product, see our MCP development service. The official MCP SDKs overview compares all ten languages by tier.

Frequently asked questions