In our previous article, we explored how to create a Model Context Protocol (MCP) server in Swift. Now, let's look at the other side of the equation: building a client application that connects to an MCP server. This guide will walk you through creating a Swift client that can communicate with any MCP-compatible server, including the one we built in our previous tutorial.

What is a MCP Client?

A Model Context Protocol (MCP) client is an application that connects to an MCP server to access its tools and capabilities. The client sends requests to the server, which processes them and returns responses. This architecture allows AI systems to extend their capabilities through external tools without needing to implement those capabilities directly.

Prerequisites

Before we begin, make sure you have:

• macOS 13.3 or later
• Swift 6.0 or later
• Xcode 15.0 or later (recommended)
• A compatible MCP server (like the one from our previous tutorial)

Step 1: Set Up Your Project

First, let's create a new Swift package for our MCP client:

mkdir SwiftMCPClientExample
cd SwiftMCPClientExample
swift package init --type executable

Next, update your Package.swift file to include the necessary dependencies:

// swift-tools-version: 6.0

import PackageDescription

let package = Package(
    name: "SwiftMCPClientExample",
    platforms: [
        .macOS("13.3")
    ],
    dependencies: [
        .package(url: "https://github.com/modelcontextprotocol/swift-sdk.git", from: "0.9.0"),
        .package(url: "https://github.com/apple/swift-log.git", from: "1.5.3"),
        .package(url: "https://github.com/glaciotech/mcp-swift-sdk-helpers.git", from: "0.2.0"),
    ],
    targets: [
        .executableTarget(
            name: "SwiftMCPClientExample",
            dependencies: [
                .product(name: "MCP", package: "swift-sdk"),
                .product(name: "MCPHelpers", package: "mcp-swift-sdk-helpers"),
            ]),
    ]
)

Step 2: Create a Configuration Structure

We'll start by creating a configuration structure to hold information about the MCP server we want to connect to. Create a new file called LocalMCProcess.swift in your Sources directory:

import MCP
import Foundation
import Logging
import System

public struct LocalMCPServerConfig: Codable {
    public var name: String
    public var executablePath: String
    public var arguments: [String]
    public var environment: [String: String]

    public init(name: String, executablePath: String, arguments: [String] = [], environment: [String: String] = [:]) {
        self.name = name
        self.executablePath = executablePath
        self.arguments = arguments
        self.environment = environment
    }
}

This structure defines the configuration needed to start and connect to a local MCP server process.

Step 3: Implement the LocalMCProcess Class

Next, we'll implement a class that manages the lifecycle of a local MCP server process. Add the following to your LocalMCProcess.swift file:

public class LocalMCProcess {

    private let config: LocalMCPServerConfig
    private var process: Process?
    private var stdinPipe: Pipe?
    private var stdoutPipe: Pipe?
    private var stderrPipe: Pipe?

    public init(config: LocalMCPServerConfig) {
        self.config = config
    }

    public func start() async throws -> Client {
        // Create pipes for stdin, stdout, and stderr
        let stdinPipe = Pipe()
        let stdoutPipe = Pipe()
        let stderrPipe = Pipe()

        // Create and configure the process
        let process = Process()
        process.executableURL = URL(fileURLWithPath: config.executablePath)
        process.arguments = config.arguments

        // Set environment variables if provided
        if !config.environment.isEmpty {
            var environment = ProcessInfo.processInfo.environment
            for (key, value) in config.environment {
                environment[key] = value
            }
            process.environment = environment
        }

        // Connect pipes to the process
        process.standardInput = stdinPipe
        process.standardOutput = stdoutPipe
        process.standardError = stderrPipe

        // Store references to prevent deallocation
        self.process = process
        self.stdinPipe = stdinPipe
        self.stdoutPipe = stdoutPipe
        self.stderrPipe = stderrPipe

        // Launch the process
        try process.run()

        // Convert FileHandles to FileDescriptors for StdioTransport
        let inputFD = FileDescriptor(rawValue: stdoutPipe.fileHandleForReading.fileDescriptor)
        let outputFD = FileDescriptor(rawValue: stdinPipe.fileHandleForWriting.fileDescriptor)

        // Create StdioTransport
        let logger = Logger(label: "mcp.transport.process.\(config.name)")
        let transport = StdioTransport(
            input: inputFD,
            output: outputFD,
            logger: logger
        )

        // Connect the client
        let client = Client(name: self.config.name, version: "1.0.0", configuration: .default)
        _ = try await client.connect(transport: transport)

        return client
    }

    public func stop() {
        // Terminate the process
        process?.terminate()

        // Close all file handles
        try? stdinPipe?.fileHandleForWriting.close()
        try? stdoutPipe?.fileHandleForReading.close()
        try? stderrPipe?.fileHandleForReading.close()

        // Clear references
        process = nil
        stdinPipe = nil
        stdoutPipe = nil
        stderrPipe = nil
    }
}

This class handles:

1. Starting the MCP server process
2. Setting up pipes for communication
3. Creating a transport layer for the MCP client
4. Connecting the client to the server
5. Cleaning up resources when done

Step 4: Create the Main Application

Now, let's create our main application that uses the LocalMCProcess class to connect to an MCP server and call its tools. Update your main.swift file:

import Foundation
import MCP
import MCPHelpers
import SwiftyJsonSchema

// MARK: - Helpers
let jsonEncoder = JSONEncoder()
let jsonDecoder = JSONDecoder()

func printToolInfo(_ tool: Tool) throws {
    print("--- TOOL INFO ---")
    print("Name: \(tool.name)")
    print("Annotations: \(tool.annotations)")

    do {
        guard let rawInputSchema = tool.inputSchema else {
            print("ERROR: No input schema in Tool info")
            return
        }
        let jsonSchema = try JSONSchema(fromValue: rawInputSchema)
        print("Schema: \(jsonSchema)")
    }
    catch {
        print("!!! Problem reading schema !!!: \(error)")
    }

    print("------------")
}


// MARK: - Test MCP

// Get the path to the MCP server executable
// You can pass this as a command-line argument or hardcode it
guard let pathToMCPExampleServerBuildDirectory = UserDefaults.standard.string(forKey: "MCP_SERVER_BUILD_PATH") else {
    fatalError("!!! YOU NEED TO DEFINE THE PATH TO YOUR MCP SERVER !!!")
}

// Create a configuration for the MCP server
let jsonConfig = """
    {
      "name": "swift-mcp-server-example",
        "executablePath": "\(pathToMCPExampleServerBuildDirectory)/Products/Debug/SwiftMCPServerExample",
        "arguments": [],
        "environment": {}
    }
    """

// Load the configuration
let config = try jsonDecoder.decode(LocalMCPServerConfig.self, from: jsonConfig.data(using: .ascii)!)

// Start the server process and connect a client
let mcp = LocalMCProcess(config: config)
let client = try await mcp.start()

// List available tools
let toolListResponse = try await client.listTools()
for tool in toolListResponse.tools {
    try printToolInfo(tool)
}

// Define a structure for the tool input
struct EchoToolInput: Codable {
    var echoText: String = ""
}

// Call the "echo" tool
let toolRequest = EchoToolInput(echoText: "Hello World from MCP Client")
let toolArgs = try Value(toolRequest).objectValue

let result = try await client.callTool(name: "echo", arguments: toolArgs)
print("RESULT FROM TOOL CALL: \(result.content.first!)")

// Clean up
mcp.stop()

Step 5: Running the Client

To run the client, you need to:

1. Build the MCP server from our previous tutorial (or any compatible MCP server)
2. Note the path to the built executable
3. Run the client with the server path as an argument

Running from Command Line

swift run SwiftMCPClientExample -MCP_SERVER_BUILD_PATH=/path/to/server/build/directory

Replace /path/to/server/build/directory with the actual path to your MCP server's build directory.

Running from Xcode

To run the project in Xcode:

1. Open the project in Xcode by opening the Package.swift file
2. Select the SwiftMCPClientExample scheme
3. Go to Product > Scheme > Edit Scheme (or press ⌘<)
4. Select the 'Run' action on the left panel
5. Go to the 'Arguments' tab
6. Under 'Arguments Passed On Launch', click the '+' button
7. Add -MCP_SERVER_BUILD_PATH=/path/to/server/build/directory (replace with the actual path to your MCP server's build directory)
8. Click 'Close' and run the project (⌘R)

Tip: You can find the build directory path in Xcode by building the MCP server project, then selecting Product > Show Build Folder in Finder.

Expected Output

When you run the client successfully, you should see output similar to the following:

--- TOOL INFO ---
Name: echo
Annotations: Annotations(title: nil, destructiveHint: nil, idempotentHint: nil, openWorldHint: nil, readOnlyHint: nil)
Schema: {
  "additionalProperties" : false,
  "properties" : {
    "echoText" : {
      "items" : {

      },
      "description" : "Text to send to the service that will be echoed back",
      "type" : "string",
      "additionalProperties" : false
    }
  },
  "items" : {

  },
  "type" : "object",
  "required" : [
    "echoText"
  ],
  "$schema" : "http:\/\/json-schema.org\/draft-07\/schema#"
}
------------
--- TOOL INFO ---
Name: selectRandom
Annotations: Annotations(title: nil, destructiveHint: nil, idempotentHint: nil, openWorldHint: nil, readOnlyHint: nil)
Schema: {
  "$schema" : "http:\/\/json-schema.org\/draft-07\/schema#",
  "properties" : {
    "ints" : {
      "items" : {
        "items" : {
          "properties" : {

          },
          "items" : {

          },
          "type" : "object",
          "required" : [

          ],
          "additionalProperties" : false
        }
      },
      "description" : "An array of integers to select one at random from",
      "type" : "array",
      "additionalProperties" : false
    }
  },
  "items" : {

  },
  "type" : "object",
  "required" : [
    "ints"
  ],
  "additionalProperties" : false
}
------------
RESULT FROM TOOL CALL: text("You sent: Hello World from MCP Client")

This output shows:

1. The tool information for the two available tools on the server ("echo" and "selectRandom")
2. The schema information for each tool
3. The result of calling the "echo" tool, which returns the text we sent

Understanding the Code

Let's break down what's happening in our client application:

1. Server Configuration

We define a LocalMCPServerConfig structure that contains all the information needed to start and connect to a local MCP server:

• name: A unique identifier for the server
• executablePath: The path to the server executable
• arguments: Command-line arguments to pass to the server
• environment: Environment variables to set for the server process

2. Process Management

The LocalMCProcess class handles the lifecycle of the MCP server process:

• It creates pipes for stdin, stdout, and stderr communication
• It launches the server process with the specified configuration
• It sets up a transport layer for the MCP client to communicate with the server
• It provides a method to stop the server and clean up resources when done

3. Client Connection

The client connects to the server using the MCP SDK's Client class:

• It creates a client instance with a name and version
• It connects to the server using the transport layer
• Once connected, it can list available tools and call them with parameters

4. Tool Discovery and Invocation

The client can discover the tools available on the server:

• It calls client.listTools() to get a list of available tools
• It can inspect each tool's name, annotations, and input schema
• It can call a tool by name with the appropriate arguments

5. Tool Calling

To call a tool, the client:

• Creates a structure representing the tool's input parameters
• Converts the structure to a dictionary of arguments
• Calls the tool with client.callTool(name:, arguments:)
• Processes the result returned by the tool

Advanced Usage

Handling Different Tool Types

The example above demonstrates calling a simple "echo" tool, but you can call any tool provided by the MCP server. For each tool, you'll need to:

1. Define a structure that matches the tool's input schema
2. Create an instance of that structure with the appropriate values
3. Convert the structure to a dictionary of arguments
4. Call the tool and process the result

Error Handling

In a production application, you should add proper error handling:

do {
    let result = try await client.callTool(name: "echo", arguments: toolArgs)
    print("Success: \(result.content.first!)")
} catch let error as MCPError {
    print("MCP Error: \(error)")
} catch {
    print("Unexpected error: \(error)")
}

Asynchronous Tool Calls

The MCP SDK uses Swift's async/await pattern for asynchronous operations. Make sure your application is set up to handle asynchronous code:

Task {
    do {
        let client = try await mcp.start()
        // Use the client...
    } catch {
        print("Error: \(error)")
    }
}

Conclusion

In this tutorial, we've built a Swift client that can connect to an MCP server and call its tools. This client can work with any MCP-compatible server, including the one we built in our previous tutorial.

The Model Context Protocol provides a standardized way for AI systems to extend their capabilities through external tools. By implementing both the server and client sides of the protocol, you can create powerful, modular AI applications that can be easily extended with new capabilities.

Next Steps

Now that you understand how to build both MCP servers and clients in Swift, you can:

1. Create your own custom tools to extend AI capabilities
2. Integrate MCP clients into your Swift applications
3. Connect your applications to AI systems that support the MCP protocol

Finding the Code on GitHub

The complete code for this tutorial is available on GitHub at github.com/glaciotech/SwiftMCPClientExample. Feel free to clone it, modify it, and use it as a starting point for your own MCP client projects.

Resources

• Model Context Protocol
• Swift MCP SDK
• Swift MCP Client Example
• Swift MCP Server Example
• Building a MCP Server in Swift: A Step-by-Step Guide

What is MCP?

MCP (Model Context Protocol) is a standard that allows AI systems like large language models (LLMs) to interact with external tools and services. By implementing an MCP server, you can extend AI capabilities with custom functionality that can be accessed through a standardized interface.

Prerequisites

Before we begin, make sure you have:

• Xcode 15 or later
• Swift 6.0 or later
• Basic knowledge of Swift and SPM (Swift Package Manager)

Creating the Project

You can create a new Swift package either using Xcode or the command line. Choose the method you prefer:

Option 1: Creating the package in Xcode

1. Open Xcode and select 'File > New > Package...'
2. Name your package 'SwiftMCPServerExample'
3. Select 'Executable' as the package type
4. Choose a location to save your project and click 'Create'

Option 2: Creating the package via command line

mkdir SwiftMCPServerExample
cd SwiftMCPServerExample
swift package init --type executable

After creating the package via command line, you can open it in Xcode by double-clicking the Package.swift file or using xed . in the terminal.

Regardless of which method you choose, we'll be using Swift Package Manager (SPM) for dependency management and building/running the project directly in Xcode for the remainder of this tutorial.

Setting Up Dependencies

Next, we need to modify the Package.swift file to include the necessary dependencies:

// swift-tools-version: 6.0
// The swift-tools-version declares the minimum version of Swift required to build this package.

import PackageDescription

let package = Package(
    name: "SwiftMCPServerExample",
    platforms: [
        .macOS(.v13) // This is optional, specify if you have a minimum macOS version requirement
    ],
    dependencies: [
        // MCP Swift SDK - the core library for implementing the Model Context Protocol, imported through `mcp-swift-sdk-helpers`
        // Uncomment this line if you want to use the core SDK directly without the helper methods
        // .package(url: "https://github.com/modelcontextprotocol/swift-sdk.git", from: "0.9.0"),

        // Service Lifecycle for managing the server lifecycle
        .package(url: "https://github.com/swift-server/swift-service-lifecycle.git", from: "2.8.0"),

        // MCP Helper package - provides utilities for encoding, decoding and producing JSON schemas
        // Comment this line if you want to use the core SDK directly without the helper methods
        .package(url: "https://github.com/glaciotech/mcp-swift-sdk-helpers.git", from: "0.1.0"),
    ],
    targets: [
        .executableTarget(
            name: "SwiftMCPServerExample",
            dependencies: [
                .product(name: "ServiceLifecycle", package: "swift-service-lifecycle"),
                // Comment this line when using the helper package
                // .product(name: "MCP", package: "swift-sdk"),

                // Use the MCPHelpers product from our helper package
                .product(name: "MCPHelpers", package: "mcp-swift-sdk-helpers")
            ]
        ),
        .testTarget(
            name: "SwiftMCPServerExampleTests",
            dependencies: [
                "SwiftMCPServerExample",
                .product(name: "ServiceLifecycle", package: "swift-service-lifecycle"),
                // Comment this line when using the helper package
                // .product(name: "MCP", package: "swift-sdk"),

                // Use the MCPHelpers product from our helper package
                .product(name: "MCPHelpers", package: "mcp-swift-sdk-helpers")
            ],
            path: "Tests"
        )
    ]
)

After updating the Package.swift file, Xcode should automatically resolve the dependencies. If not, you can reset the package cache by going to File > Packages > Reset Package Caches, or run this command in the terminal:

swift package resolve

This will download and resolve all the dependencies.

About the MCP Helper Package

In this tutorial, we're using an MCP Helper package that wraps the core modelcontextprotocol/swift-sdk and adds some helpful utilities:

• JSON Schema Generation: Makes it easier to define the input/output schemas for your tools
• Parameter Initialization: Simplifies parsing incoming parameters from the LLM
• Type-Safe Models: Provides strongly-typed Swift models for your tool inputs and outputs

This helper package makes it much easier to create MCP servers by reducing boilerplate code and providing a more Swift-idiomatic API.

Creating the Project Structure

Now, let's create the files we need for our MCP server. In Xcode, right-click on the 'Sources' folder and select 'New File...' to create each of the following files:

1. MCPServerFactory.swift - Factory for creating and configuring the MCP server
2. MCPService.swift - Service for managing the MCP server lifecycle
3. We'll also modify the existing main.swift file

Defining Tool Input Schemas and Enums

First, let's define the input schemas for our tools and an enum to keep track of our registered tools in MCPServerFactory.swift:

import Foundation
import SwiftyJsonSchema
import ServiceLifecycle
import MCP
import Logging
import MCPHelpers

// We make use of SwiftyJsonSchema to generate the JSON schema that informs the LLM of how to structure the tool call
struct EchoToolInput: ProducesJSONSchema, ParamInitializable {
    static let exampleValue = EchoToolInput(echoText: "Echo...")

    @SchemaInfo(description: "Text to send to the service that will be echoed back")
    var echoText: String = ""
}

struct PickRandomToolInput: ProducesJSONSchema, ParamInitializable {
    static let exampleValue = PickRandomToolInput(ints: [5, 4, 6, 7, 123, 8411])

    @SchemaInfo(description: "An array of integers to select one at random from")
    var ints: [Int]? = nil
}

enum RegisteredTools: String {
    case echo
    case selectRandom
}

Creating the MCP Server Factory

Next, let's implement the MCPServerFactory class that will create and configure our MCP server:

/// MCPSeverFactory creates and configures our server with the example Tools and Prompts
class MCPServerFactory {

    /// This creates a new instance of a configured MCP server with our Tools ready to go
    static func makeServer(with logger: Logger) async -> Server {
        // Create our server
        let server = Server(name: "ExampleSwiftMCPServer",
                            version: "1.0",
                            capabilities: .init(logging: Server.Capabilities.Logging(),
                                                resources: .init(subscribe: true, listChanged: true),
                                                tools: .init(listChanged: true)
        ))

        // Register the tools
        await registerTools(on: server)

        // Setup the code to handle the tool logic when we receive a request for that tool
        await server.withMethodHandler(CallTool.self, handler: toolsHandler)

        return server
    }
}

Creating and Implementing the Echo Tool

Now, let's implement the Echo tool. This tool simply returns whatever text is sent to it. Add the following to the MCPServerFactory class:

// Echo tool handler implementation
private static func echoHandler(_ text: String) -> String {
    return text
}

Creating and Implementing the Random Selector Tool

Next, let's implement the Random Selector tool. This tool takes an array of integers and returns a random element from the array:

// Random selector tool handler implementation
private static func pickRandomNumberHandler(_ numbers: [Int]?) -> Int {
    guard let numbers = numbers else {
        return .zero
    }
    return numbers.randomElement() ?? .zero
}

Registering the Tools with the MCP Server

Now, let's register our tools with the MCP server. Add this method to the MCPServerFactory class:

private static func registerTools(on server: Server) async {
    /// Register a tool list handler
    await server.withMethodHandler(ListTools.self) { _ in

        // Define 2 simple tools: an echo tool that just returns whatever the LLM sends
        // and a random selector tool that picks a random number from an array
        let tools = [
            Tool(
                name: RegisteredTools.echo.rawValue,
                description: "Echo back any text that was sent",
                inputSchema: try .produced(from: EchoToolInput.self)
            ),
            Tool(
                name: RegisteredTools.selectRandom.rawValue,
                description: "Takes in a collection of numbers or strings and picks one at random",
                inputSchema: try .produced(from: PickRandomToolInput.self)
            )
        ]
        return .init(tools: tools)
    }
}

Implementing the Tool Handler

Finally, let's implement the tool handler that processes incoming tool requests and routes them to the appropriate handler:

static func toolsHandler(params: CallTool.Parameters) async throws -> CallTool.Result {
    let unknownToolError = CallTool.Result(content: [.text("Unknown tool")], isError: true)

    // Convert tool name to our enum
    guard let tool = RegisteredTools(rawValue: params.name) else {
        return unknownToolError
    }

    switch tool {
    case RegisteredTools.echo:
        let input = try EchoToolInput(with: params)
        let result = echoHandler(input.echoText)
        return .init(
            content: [.text("You sent: \(result)")],
            isError: false
        )

    case RegisteredTools.selectRandom:
        let input = try PickRandomToolInput(with: params)
        let result = self.pickRandomNumberHandler(input.ints)
        return .init(
            content: [.text("I picked: \(result)")],
            isError: false
        )
    }
}

Creating the MCP Service

Now, let's create the MCPService.swift file that will handle the lifecycle of our MCP server:

import MCP
import ServiceLifecycle
import Logging

struct MCPService: Service {

    let server: Server
    let transport: StdioTransport

    init(server: Server, transport: StdioTransport) {
        self.server = server
        self.transport = transport
    }

    func run() async throws {
        // Start the server
        try await server.start(transport: transport)

        // Keep running until external cancellation
        try await Task.sleep(for: .seconds(10000)) 
    }

    func shutdown() async throws {
        // Gracefully shutdown the server
        await server.stop()
    }
}

Setting Up the Main Application

Finally, let's implement the main.swift file to tie everything together:

import MCP
import ServiceLifecycle
import Foundation
import Logging

final class App: Sendable {

    // Create a logging object we'll hand to other parts of the project
    let log = {
        var logger = Logger(label: "tech.glacio.mcpserverexample")
        logger.logLevel = .debug
        return logger
    }()

    /// Create and start our MCP service, we make use of a ServiceGroup to handle launching and shutting down the server
    func start() async throws {

        log.info("App has started")

        // Create the configured server with registered Tools and the MCP service
        let transport = StdioTransport(logger: log)
        let server = await MCPServerFactory.makeServer(with: log)
        let mcpService = MCPService(server: server, transport: transport)

        // Create service group with signal handling
        let serviceGroup = ServiceGroup(services: [mcpService],
                                        gracefulShutdownSignals: [.sigterm, .sigint],
                                        logger: log)

        // Run the service group - this blocks until shutdown
        try await serviceGroup.run()
    }
}

// Start the app
try! await App().start()

Example of testing the tool call logic

To test our MCP server, let's create a simple test in Tests/MCPTest.swift:

import XCTest
import MCP
@testable import SwiftMCPServerExample
import Logging

final class MCPTest: XCTestCase {

    func testToolHandler() async throws {
        // Test the echo tool
        let echoToolParams = CallTool.Parameters(name: RegisteredTools.echo.rawValue, 
                                                arguments: ["echoText": "Test Text To Echo"])

        let echoResult = try await MCPServerFactory.toolsHandler(params: echoToolParams)
        XCTAssertEqual(echoResult.content.first?.text, "You sent: Test Text To Echo")
        XCTAssertFalse(echoResult.isError)

        // Test the random selector tool
        let testNumbers = [1, 2, 3, 4, 5]
        let randomToolParams = CallTool.Parameters(name: RegisteredTools.selectRandom.rawValue,
                                                  arguments: ["ints": testNumbers])

        let randomResult = try await MCPServerFactory.toolsHandler(params: randomToolParams)
        XCTAssertFalse(randomResult.isError)

        // Test with an unknown tool
        let unknownToolParams = CallTool.Parameters(name: "unknownTool", arguments: [:])
        let unknownResult = try await MCPServerFactory.toolsHandler(params: unknownToolParams)
        XCTAssertTrue(unknownResult.isError)
    }
}

Run the tests with:

swift test

Building the MCP Server

Before using your MCP server with Windsurf, you need to build it:

In Xcode:

1. Select the 'SwiftMCPServerExample' scheme from the scheme selector
2. Build the project by pressing Cmd+B

Alternatively, you can build from the terminal:

swift build

Note that running the MCP server directly doesn't do much on its own - it will just wait for input on stdin. The real power comes when Windsurf launches it automatically as an MCP plugin.

Testing and Using Your MCP Server in Windsurf

To use your MCP server with Windsurf (an AI development environment), you need to add it to your MCP Server configuration file. Once properly configured, Windsurf will automatically launch your MCP server when needed - you don't need to run it manually.

{
  "mcpServers": {
    "swift-mcp-server-example": {
      "command": "{XCODE_BUILD_FOLDER}/Products/Debug/SwiftMCPServerExample",
      "args": [],
      "env": {}
    }
  }
}

Replace {XCODE_BUILD_FOLDER} with your actual build folder path. In Xcode, you can find this by going to Product -> Copy Build Folder Path.

After adding this configuration, click the "Refresh" button in Windsurf to discover your new MCP Server. Windsurf will automatically launch your MCP server when needed. You can see the available MCP servers in Windsurf as shown in the screenshot below:

Screenshot: Windsurf interface showing available MCP servers including swift-mcp-server-example with 2 tools and mcp-server-firecrawl with 9 tools

Once your MCP server is running and connected to Windsurf, you can interact with it through Cascade. Here are examples of how to use the tools:

Using the Random Selector Tool

You can ask Cascade to generate a list of random numbers and use the selectRandom tool to pick one:

Screenshot: Using the selectRandom tool to pick a random number from a list of integers 1-10. The tool selected 7.

Using the Echo Tool

You can also use the echo tool to have text echoed back to you:

Screenshot: Using the echo tool to have the text "Hello Windsurf" echoed back.

As you can see from these examples, once your MCP server is properly configured in Windsurf, Cascade can seamlessly access and utilize your custom tools.

Extending Your MCP Server

Now that you have a basic MCP server working, you can extend it with more sophisticated tools. Here are some ideas:

1. Add a weather data tool that fetches real-time weather information
2. Create a calculator tool that can evaluate mathematical expressions
3. Implement a translation tool that uses a third-party API
4. Build a database query tool that can retrieve and manipulate data

Troubleshooting

If you encounter issues with your MCP server in Windsurf:

1. Make sure you've built the project first
2. Try closing Windsurf
3. Kill any running MCP server processes in Activity Monitor
4. Relaunch Windsurf

You can also try these additional troubleshooting steps:

• Edit the MCP config file: You can disable problematic MCP servers by commenting them out in your MCP configuration file or adding a "disabled": true property to the server configuration. The MCP config can be accessed by going to Windsurf Settings → Cascade -> Manage Plugins and clicking on the "View raw config" button.

{
  "mcpServers": {
    "swift-mcp-server-example": {
      "command": "{XCODE_BUILD_FOLDER}/Products/Debug/SwiftMCPServerExample",
      "args": [],
      "env": {},
      "disabled": true  // Add this line to disable the server
    }
  }
}

• View MCP server errors: You can check for errors in your MCP server by going to Windsurf Settings → Cascade -> Manage Plugins. This section displays the status of each MCP server and any error messages that might help diagnose issues.

Finding the Code on GitHub

The complete code for this tutorial is available on GitHub at github.com/glaciotech/SwiftMCPServerExample. Feel free to clone it, modify it, and use it as a starting point for your own MCP server projects.

Conclusion

In this tutorial, we've built a simple MCP server in Swift that provides two tools: an echo tool and a random number selector. We've learned how to:

1. Set up a Swift package with the necessary dependencies
2. Define tool input schemas using SwiftyJsonSchema
3. Create and configure an MCP server
4. Implement tool handlers
5. Test the MCP server
6. Integrate the server with Windsurf

MCP servers provide a powerful way to extend AI capabilities with custom tools and services. With the knowledge gained from this tutorial, you can now build more sophisticated MCP servers to meet your specific needs.

Happy coding!