# Swift Fast Mcp

> The fastest way to build MCP servers in Swift.

- **Type:** MCP server
- **Install:** `agentstack add mcp-mehmetbaykar-swift-fast-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [mehmetbaykar](https://agentstack.voostack.com/s/mehmetbaykar)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [mehmetbaykar](https://github.com/mehmetbaykar)
- **Source:** https://github.com/mehmetbaykar/swift-fast-mcp

## Install

```sh
agentstack add mcp-mehmetbaykar-swift-fast-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# FastMCP

The fastest way to build MCP servers in Swift.

If you found this helpful, you can support more open source work!

---

```swift
try await FastMCP.builder()
    .name("My Server")
    .addTools([WeatherTool()])
    .run()
```

Three lines to a working MCP server over stdio. Or serve over HTTP:

```swift
try await FastMCP.builder()
    .name("My Server")
    .addTools([WeatherTool()])
    .transport(.http(port: 8080))
    .run()
```

Or aggregate tools from another Streamable HTTP MCP server and expose them
beside your local Swift tools:

```swift
try await FastMCP.builder()
    .name("Gateway")
    .addTools([WeatherTool()])
    .addUpstreamMCPServers([
        .streamableHTTP(
            name: "firecrawl",
            endpoint: URL(string: "https://mcp.firecrawl.dev/v2/mcp")!,
            headers: ["Authorization": "Bearer "]
        )
    ])
    .run()
```

## Installation

Add to your `Package.swift`:

```swift
dependencies: [
    .package(url: "https://github.com/mehmetbaykar/swift-fast-mcp", from: "2.7.0")
]
```

Then add `"FastMCP"` as a dependency of your target:

```swift
.target(
    name: "MyServer",
    dependencies: [
        .product(name: "FastMCP", package: "swift-fast-mcp")
    ]
)
```

FastMCP pulls in these dependencies automatically:

- [swift-sdk](https://github.com/modelcontextprotocol/swift-sdk) -- Official MCP Swift SDK
- [swift-ai-hub](https://github.com/mehmetbaykar/swift-ai-hub) -- `@Tool` / `@Generable` / `@Parameter` / `@Guide` macros and the `Tool` protocol surface
- [swift-service-lifecycle](https://github.com/swift-server/swift-service-lifecycle) -- Graceful shutdown
- [swift-syntax](https://github.com/swiftlang/swift-syntax) -- Compiler plugin for `@MCPPrompt` / `@MCPResource`
- [swift-nio](https://github.com/apple/swift-nio) -- HTTP transport (NIO is an internal dependency; not re-exported)

`FastMCPAIBridge` is intentionally public and re-exported by `FastMCP` for
advanced bridge testing and custom adapter use. Most applications should still
prefer the builder APIs.

## Quick Start

### Stdio transport (default)

```swift
import FastMCP

@Tool("Get weather for a location")
struct WeatherTool {
    @Parameter("City or coordinates")
    var location: String = ""

    func execute() async throws -> String {
        "Weather in \(location): 22°C, Sunny"
    }
}

@main
struct MyServer {
    static func main() async throws {
        try await FastMCP.builder()
            .name("Weather Server")
            .addTools([WeatherTool()])
            .run()
    }
}
```

Connect it to Claude Desktop by adding to `claude_desktop_config.json`:

```json
{
    "mcpServers": {
        "weather": {
            "command": "/path/to/my-server"
        }
    }
}
```

### HTTP transport

```swift
@main
struct MyServer {
    static func main() async throws {
        try await FastMCP.builder()
            .name("Weather Server")
            .addTools([WeatherTool()])
            .transport(.http(port: 8080))
            .run()
        // Listening on http://127.0.0.1:8080/mcp
    }
}
```

## Transport Options

```swift
public enum Transport: Sendable {
    case stdio
    case inMemory
    case http(
        mode: HTTPMode = .stateful,
        host: String = "127.0.0.1",
        port: Int = 3000,
        endpoint: String = "/mcp"
    )
    case custom(MCP.Transport)
}
```

| Transport | Use Case |
|-----------|----------|
| `.stdio` | Claude Desktop, CLI tools. Default. |
| `.inMemory` | Unit testing. |
| `.http(...)` | Remote servers, multi-client access, web deployments. |
| `.custom(transport)` | Provide your own `MCP.Transport` implementation. |

### HTTPMode

```swift
public enum HTTPMode: Sendable {
    case stateful
    case stateless
}
```

**Stateful** (default) -- Full MCP Streamable HTTP. Each client gets a session with SSE streaming, resumability via `Last-Event-ID`, GET for server-initiated messages, and DELETE for session teardown.

**Stateless** -- Minimal HTTP. No sessions, direct JSON responses, POST only. Use when session management is handled externally or not needed.

```swift
// Stateful (default)
.transport(.http(port: 8080))
.transport(.http(mode: .stateful, host: "0.0.0.0", port: 3000, endpoint: "/mcp"))

// Stateless
.transport(.http(mode: .stateless, port: 8080))
```

## Builder API

All builder methods return a new `Builder` (value semantics) and can be chained.

### Server metadata

```swift
.name("My Server")               // Server name (default: process name)
.version("2.7.0")                // Server version (default: "1.0.0")
.title("My Display Name")        // Human-readable display name for UIs
.instructions("Use this server to...") // Instructions for LLM clients
.icons([...])                     // Server icons for display in UIs
```

### Capabilities

```swift
try FastMCP.builder()
    .addTools([WeatherTool(), MathTool(), StructuredSearchTool()])   // Register tool implementations
    .addUpstreamMCPServers([                  // Proxy Streamable HTTP upstream tools as docs_*
        .streamableHTTP(name: "docs", endpoint: docsMCPURL)
    ])
    .addResources([ConfigResource()])         // Register resource implementations
    .addPrompts([GreetingPrompt()])           // Register prompt implementations
    .enableCompletions()                      // Advertise completions capability
    .enableLogging()                          // Advertise logging capability
```

Duplicate upstream server names and tool names fail early. Resources and prompts
are deduplicated automatically; the first registration wins.

Deferred SwiftAIHub tool sources resolve asynchronously, so `addTools(_:)` is
also available as an `async throws` builder call:

```swift
import FastMCP

try await FastMCP.builder()
    .addTools(localOrDeferredToolSource)
    .run()
```

Use `addUpstreamMCPServers(...)` when you want FastMCP to act as an MCP gateway
for remote MCP tools while preserving their MCP descriptors and call results.

### Transport and infrastructure

```swift
.transport(.stdio)                       // Transport selection (default: .stdio)
.logger(myLogger)                        // Custom swift-log Logger
.shutdownSignals([.sigterm, .sigint])    // Unix signals for graceful shutdown (default: both)
```

### Lifecycle hooks

Under `.stdio` (the default), stdout carries JSON-RPC frames — do not use `print` in hooks. Route messages through the injected `Logger` instead (swift-log's default handler writes to stderr). Under `.http`, either approach is safe.

```swift
.onStart { logger.info("Server started") }
.onShutdown { logger.info("Server stopped") }
.onInitialize { clientInfo, capabilities in
    // Called when a client sends an initialize request.
    // Receives Client.Info and Client.Capabilities.
    // Useful for auth checks, logging, per-client setup.
    // Especially valuable for HTTP where multiple clients connect.
    logger.info("Client: \(clientInfo.name) v\(clientInfo.version)")
}
```

### HTTP-specific configuration

```swift
.sessionTimeout(.seconds(1800))          // Idle session timeout (default: 3600s)
                                          // Only applies to .http with .stateful mode.

.httpValidation(
    allowedOrigins: ["https://example.com"],  // Allowed Origin headers (default: localhost only)
    customValidators: [MyAuthValidator()]     // Custom HTTPRequestValidator implementations
)
```

### Running

```swift
.run()  // Starts the server and blocks until shutdown
```

## HTTP Transport

### Multi-session model

In stateful HTTP mode, each connecting client gets its own independent `Server` + `Transport` pair. The server manages session lifecycle automatically.

### Session lifecycle (stateful mode)

1. Client sends POST to `/mcp` with an `initialize` JSON-RPC request (no session header).
2. Server creates a new `StatefulHTTPServerTransport` + `Server` pair, registers all tools/resources/prompts.
3. Transport generates a session ID, returned in the `Mcp-Session-Id` response header.
4. Subsequent requests include this header and are routed to the matching session.
5. Client sends DELETE to terminate the session.
6. A cleanup loop runs every 60 seconds, removing sessions idle longer than `sessionTimeout`.

### Stateless mode

1. Client sends POST to `/mcp` with a JSON-RPC request.
2. Server responds with direct JSON. No SSE, no session headers, no session tracking.

### Validation pipeline

The HTTP server validates incoming requests before processing. By default, only localhost origins are allowed.

To allow remote origins or add custom validation (e.g., bearer token auth), use `.httpValidation()`:

```swift
.httpValidation(
    allowedOrigins: ["https://myapp.com", "https://staging.myapp.com"],
    customValidators: [BearerTokenValidator(expectedToken: "...")]
)
```

Custom validators conform to `HTTPRequestValidator` from the MCP SDK.

### TLS

FastMCP does not handle TLS. Deploy behind a reverse proxy (nginx, Caddy) for HTTPS.

## Tools

AI-callable functions with JSON Schema generated from either flat `@Parameter`
stored properties plus `execute()`, or a nested `@Generable` `Arguments` struct
plus `execute(_:)`. The tool's name is derived from the struct name
(`MathTool` → `math`) and its return type from the body of `execute`:

```swift
@Generable
enum Operation: String, CaseIterable {
    case add, subtract, multiply, divide
}

@Tool("Perform math operations")
struct MathTool {
    @Generable
    struct Arguments {
        @Parameter("Operation") var operation: Operation
        @Parameter("First operand") var a: Double
        @Parameter("Second operand") var b: Double
    }

    func execute(_ arguments: Arguments) async throws -> String {
        let result = switch arguments.operation {
        case .add: arguments.a + arguments.b
        case .subtract: arguments.a - arguments.b
        case .multiply: arguments.a * arguments.b
        case .divide: arguments.a / arguments.b
        }
        return "Result: \(result)"
    }
}
```

## Resources

Expose data to AI models:

```swift
@MCPResource(
    "config://app/settings",
    name: "App Settings",
    description: "Application configuration",
    mimeType: .applicationJSON
)
struct ConfigResource {
    @ResourceContentBuilder
    var content: Content {
        """
        {"theme": "dark", "version": "1.0.0"}
        """
    }
}
```

## Prompts

Reusable conversation templates with typed arguments via `@PromptArgument`:

```swift
@MCPPrompt("A greeting template")
struct GreetingPrompt {
    @PromptArgument("Who to greet")
    var name: String

    @PromptArgument("Use formal tone")
    var formal: Bool = false

    func getMessages() async throws -> Messages {
        if formal {
            return [
                .user("You are a formal assistant helping \(name)."),
                .assistant("Good day, \(name). How may I assist you?"),
            ]
        } else {
            return [
                .user("You are a friendly assistant helping \(name)."),
                .assistant("Hey \(name)! What can I help you with?"),
            ]
        }
    }
}
```

## Full Example

A complete stdio server with tools, resources, prompts, and lifecycle hooks — the canonical MCP setup for Claude Desktop and CLI clients that spawn the server as a subprocess. This matches the stdio transport/lifecycle pattern used in the shipped `Sources/Example/ExampleServer.swift` (which wires up its own tools and metadata). For an HTTP-specific variant (with `.httpValidation`, `.sessionTimeout`, etc.), see the [HTTP transport](#http-transport) section above.

```swift
import FastMCP
import Logging

@main
struct ExampleServer {
    static func main() async throws {
        let logger: Logger = {
            var log = Logger(label: "my-server")
            log.logLevel = .info
            return log
        }()

        try await FastMCP.builder()
            .name("Example Server")
            .title("Example MCP Server")
            .version("2.7.0")
            .instructions("This server provides weather, math, and structured search tools.")

            .addTools([WeatherTool(), MathTool(), StructuredSearchTool()])
            .addResources([ConfigResource()])
            .addPrompts([GreetingPrompt()])

            .enableCompletions()
            .enableLogging()

            .transport(.stdio)

            .logger(logger)
            .shutdownSignals([.sigterm, .sigint])

            // Stdio owns stdout for JSON-RPC framing — route lifecycle messages
            // through `logger` (stderr) so `print` never corrupts the wire.
            .onInitialize { clientInfo, _ in
                logger.info("Client connected: \(clientInfo.name) v\(clientInfo.version)")
            }
            .onStart {
                logger.info("Server started on stdio")
            }
            .onShutdown {
                logger.info("Server shutting down")
            }

            .run()
    }
}
```

## Platform Support

- macOS 14+
- Linux (via `#if canImport(FoundationNetworking)` guards)
- Swift 6.2+

## Claude Code Integration

FastMCP ships with a [Claude Code skill](https://docs.anthropic.com/en/docs/claude-code/skills) and a [subagent](https://docs.anthropic.com/en/docs/claude-code/sub-agents) that let Claude Code scaffold and build MCP server projects for you.

### Setup

Copy the `skills/` and `.claude/` directories into your project:

```bash
# Copy the skill (project scaffolding)
cp -r skills/ .claude/skills/

# Copy the agent (expert assistance)
cp -r .claude/agents/ .claude/agents/
```

### Usage

**Scaffold a new project** with the skill:

```
/swift-fast-mcp MyServer tools,resources,prompts
```

Claude generates a complete project with Package.swift, typed tools/resources/prompts, tests, and Claude Desktop configuration.

**Get expert help** with the subagent:

Claude automatically delegates to the `swift-mcp-expert` agent when you ask about `@Tool`, `@MCPResource`, `@MCPPrompt` implementations, the builder API, `@Generable` types, or testing patterns. You can also invoke it explicitly:

```
Use the swift-mcp-expert to help me build a weather tool
```

## Documentation

- [docs/Tools.md](docs/Tools.md) — exposing `@Tool` structs from swift-ai-hub through an MCP server
- [docs/PromptsResources.md](docs/PromptsResources.md) — `@MCPPrompt`, `@MCPResource`, `@PromptArgument`, `MCPResourceMimeType`
- [docs/Transports.md](docs/Transports.md) — stdio, HTTP (stateful / stateless), in-memory, custom; `httpValidation`; ServiceGroup lifecycle
- [docs/DynamicServers.md](docs/DynamicServers.md) — `FastMCPServerHandle` for adding / removing tools, resources, and prompts after `run()` starts

The `@Tool`, `@Generable`, `@Parameter`, and `@Guide` macros come from
[swift-ai-hub](https://github.com/mehmetbaykar/swift-ai-hub) — see its
[docs/Macros.md](https://github.com/mehmetbaykar/swift-ai-hub/blob/main/docs/Macros.md)
for the macro reference.

## License

MIT

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [mehmetbaykar](https://github.com/mehmetbaykar)
- **Source:** [mehmetbaykar/swift-fast-mcp](https://github.com/mehmetbaykar/swift-fast-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** yes
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-mehmetbaykar-swift-fast-mcp
- Seller: https://agentstack.voostack.com/s/mehmetbaykar
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.