MCPKit

MCPKit is a small Swift framework for embedding an authenticated, loopback-only JSON-RPC transport in a macOS or iOS application. A native host supplies the MCP method behavior and decides which local tools or data to expose.

The project is intentionally narrow: transport, request/response types, rotating bearer-token authentication, and local discovery. It is not a complete MCP SDK, tool sandbox, permission system, or general-purpose HTTP server.

What it provides

• JSON-RPC request, response, error, and untyped JSON value types
• HTTP POST /mcp transport bound to the loopback interface
• A per-launch 256-bit bearer token checked with constant-time comparison
• User-only handshake and discovery files for deliberate local-client integration
• A delegate boundary through which the host implements MCP methods
• A bounded request size and a small test suite

Requirements

• Swift 6+
• macOS 15+
• iOS 17+

Installation

Add the package URL in Xcode or in Package.swift:

.package(url: "https://github.com/alphonsowoodbury/MCPKit.git", branch: "main")

Then add MCPKit to the target that hosts the server.

Usage

The host delegate owns protocol behavior. This minimal example implements only ping:

import MCPKit

final class AppMCPDelegate: MCPServerDelegate {
    let appName = "Example"
    let appVersion = "0.1.0"

    func handle(
        method: String,
        params: JSONValue?
    ) async -> Result<JSONValue, RPCError> {
        switch method {
        case "ping":
            return .success(.object([:]))
        default:
            return .failure(.methodNotFound)
        }
    }
}

@MainActor
func startServer() async {
    let authDirectory = FileManager.default
        .urls(for: .applicationSupportDirectory, in: .userDomainMask)[0]
        .appendingPathComponent("Example/MCP", isDirectory: true)

    let server = MCPServer(
        delegate: AppMCPDelegate(),
        authDirectory: authDirectory
    )

    await server.start()
    // Retain `server` for as long as the endpoint should remain available.
}

When the listener becomes ready, MCPKit writes:

• <authDirectory>/auth
• ~/.mcp-local/<sanitized-app-name>.json

Both contain the loopback endpoint and rotating bearer token and are written with user-only permissions. MCPKit does not edit Claude, Codex, or any other client's configuration.

Host responsibilities

The host must implement and test the MCP methods it advertises, validate tool arguments, enforce capability-level authorization, and obtain user approval for consequential actions. See SECURITY.md for the complete trust boundary.

Protocol scope

MCP.protocolVersion identifies the version a host may use in its own initialize response. MCPKit does not automatically implement initialize, tools/list, tools/call, sessions, streaming, notifications, or capability negotiation. Do not claim conformance for methods the host has not implemented and tested.

Development

swift build
swift test

License

MIT — see LICENSE.