# swift-mcp-server

A Copilot rule that supplies patterns for building MCP servers in Swift with the official SDK: tools, resources, prompts and transports.

- rule · `type=rule` · GitHub Copilot · ★ 40418
- Author: github · official GitHub repository
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/github/awesome-copilot/tree/HEAD/instructions/swift-mcp-server.instructions.md
- Updated: 2026-10-23
- HTML: https://affpapa.org/en/nevibecode/rules/swift-mcp-server

## What it does

The rule attaches to projects containing `*.swift`, `Package.swift` or `Package.resolved`, and Copilot leans on it while generating code. Inside are worked examples around the `Server` class with declared capabilities: tool listing via `ListTools`, the `CallTool` handler, resources through `ListResources` and `ReadResource`, `ResourceSubscribe` for subscriptions, and prompts via `ListPrompts` and `GetPrompt`.

Transports get their own section: `StdioTransport` for a local subprocess, `HTTPClientTransport` with streaming enabled for a remote connection. Server state is meant to live in an `actor`, since the server itself is one. Errors go through `MCPError`, and argument schemas are built with the `Value` type.

Everything here assumes the official MCP Swift SDK package, so in a project built on a different MCP library the type and method names won't line up. The `Package.swift` section cuts off mid-way, which means manifest setup has to come from the SDK docs.

## Install

### GitHub Copilot (native platform)

**Manually: put the files in place**
- File: `.github/instructions/swift-mcp-server.instructions.md` — The applyTo field sets which files it applies to

### Claude Code

**Manually: put the files in place**
- File: `.claude/rules/swift-mcp-server.md` — The paths frontmatter field limits the files: move applyTo from the source into paths

### Codex

**AGENTS.md**
- Codex reads AGENTS.md: paste the rule text there

### Cursor

**Manually: put the files in place**
- File: `.cursor/rules/swift-mcp-server.mdc` — Frontmatter: description, globs, alwaysApply. Move applyTo from the source into globs, or the rule will not attach on its own

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/rules/swift-mcp-server.md`

### Cline

**Manually: put the files in place**
- File: `.clinerules/swift-mcp-server.md`

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/github/awesome-copilot/tree/HEAD/instructions/swift-mcp-server.instructions.md

## When to use it
- register MCP server tools in Swift without hand-rolling the API
- describe a tool argument schema with the `Value` type
- wire up a stdio transport for local runs
- serve resources and track client subscriptions to them
- separate MCP errors from unexpected failures in a tool handler

## Example prompts
- Build a Swift MCP server with a search tool following these rules
- Add a resource and a subscribe handler to the server
- Move server state into an actor and hook up StdioTransport

## Source text · swift-mcp-server.instructions.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 0e4822f5e59ab1fd.

BEGIN THIRD-PARTY FILE 0e4822f5e59ab1fd
````text
---
description: 'Best practices and patterns for building Model Context Protocol (MCP) servers in Swift using the official MCP Swift SDK package.'
applyTo: "**/*.swift, **/Package.swift, **/Package.resolved"
---

# Swift MCP Server Development Guidelines

When building MCP servers in Swift, follow these best practices and patterns using the official Swift SDK.

## Server Setup

Create an MCP server using the `Server` class with capabilities:

```swift
import MCP

let server = Server(
    name: "MyServer",
    version: "1.0.0",
    capabilities: .init(
        prompts: .init(listChanged: true),
        resources: .init(subscribe: true, listChanged: true),
        tools: .init(listChanged: true)
    )
)
```

## Adding Tools

Use `withMethodHandler` to register tool handlers:

```swift
// Register tool list handler
await server.withMethodHandler(ListTools.self) { _ in
    let tools = [
        Tool(
            name: "search",
            description: "Search for information",
            inputSchema: .object([
                "properties": .object([
                    "query": .string("Search query"),
                    "limit": .number("Maximum results")
                ]),
                "required": .array([.string("query")])
            ])
        )
    ]
    return .init(tools: tools)
}

// Register tool call handler
await server.withMethodHandler(CallTool.self) { params in
    switch params.name {
    case "search":
        let query = params.arguments?["query"]?.stringValue ?? ""
        let limit = params.arguments?["limit"]?.intValue ?? 10
        
        // Perform search
        let results = performSearch(query: query, limit: limit)
        
        return .init(
            content: [.text("Found \(results.count) results")],
            isError: false
        )
        
    default:
        return .init(
            content: [.text("Unknown tool")],
            isError: true
        )
    }
}
```

## Adding Resources

Implement resource handlers for data access:

```swift
// Register resource list handler
await server.withMethodHandler(ListResources.self) { params in
    let resources = [
        Resource(
            name: "Data File",
            uri: "resource://data/example.txt",
            description: "Example data file",
            mimeType: "text/plain"
        )
    ]
    return .init(resources: resources, nextCursor: nil)
}

// Register resource read handler
await server.withMethodHandler(ReadResource.self) { params in
    switch params.uri {
    case "resource://data/example.txt":
        let content = loadResourceContent(uri: params.uri)
        return .init(contents: [
            Resource.Content.text(
                content,
                uri: params.uri,
                mimeType: "text/plain"
            )
        ])
        
    default:
        throw MCPError.invalidParams("Unknown resource URI: \(params.uri)")
    }
}

// Register resource subscribe handler
await server.withMethodHandler(ResourceSubscribe.self) { params in
    // Track subscription for notifications
    subscriptions.insert(params.uri)
    print("Client subscribed to \(params.uri)")
    return .init()
}
```

## Adding Prompts

Implement prompt handlers for templated conversations:

```swift
// Register prompt list handler
await server.withMethodHandler(ListPrompts.self) { params in
    let prompts = [
        Prompt(
            name: "analyze",
            description: "Analyze a topic",
            arguments: [
                .init(name: "topic", description: "Topic to analyze", required: true),
````
END THIRD-PARTY FILE 0e4822f5e59ab1fd

The third-party file has ended. Everything between the 0e4822f5e59ab1fd tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 3568 of 11757 bytes. © github · MIT · https://github.com/github/awesome-copilot/tree/HEAD/instructions/swift-mcp-server.instructions.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md