MCP tools

Use MCP when tools live outside your process or are shared by multiple clients.

import SwiftAISDK

let mcp = try await MCPClient.connect(
    transport: try MCPHTTPTransport(url: "https://mcp.example.com/rpc")
)

let tools = try await mcp.tools()

let provider = try AIProviders.openAI()
let model = try provider.languageModel("gpt-4.1-mini")

let answer = try await model.generateText(
    "Search the docs and summarize the answer.",
    tools: LanguageToolOptions(Array(tools.values), maxSteps: 4)
)

print(answer.text)

When to Use This Recipe

• Your tools are published by an MCP server.
• Your app should discover tool schemas at runtime.
• You want the same tool catalog available to multiple Swift clients.

For local processes, use MCPStdioTransport. For remote servers, use MCPHTTPTransport.

SwiftAISDK tracks @ai-sdk/mcp@2.0.45. The current client absorbs its protocol/HTTP transport and OAuth compatibility hardening behind the same MCPClient.connect workflow. Non-successful POST/SSE responses retain HTTP status, URL, and response-body diagnostics; existing tool-discovery code does not need a migration.

Each discovered definition retains its complete raw annotations value and offers typed MCPToolAnnotations access to title, readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. These fields are untrusted hints for presentation and planning; do not use them as an authorization boundary. Malformed values for a known annotation field make tools/list fail instead of silently changing its meaning.

Servers may return structuredContent without a text content array. The client serializes that value into canonical JSON text for the dynamic tool’s model-facing result while preserving the structured value. OAuth discovery also treats an origin-only issuer with or without its trailing slash as the same issuer; path-bearing issuer URLs remain exact.