Open Agent SDK uses MCP (Model Context Protocol) to unify external tools, remote services, and in-process capabilities within the Agent loop, solving common problems in Agent tool extensibility, fragmented protocol adaptation, and runtime management. Keywords: Open Agent SDK, MCP, Swift Agent.
Technical Specification Snapshot
| Parameter | Description |
|---|---|
| Project | Open Agent SDK (Swift) |
| Core Topic | MCP integration and Agent tool extensibility |
| Language | Swift |
| Protocols | MCP, JSON-RPC |
| Transports | stdio, HTTP, SSE, in-process SDK, ClaudeAI Proxy |
| Typical Dependencies | Foundation Process, FileDescriptor, HTTPClientTransport |
| Repository | terryso/open-agent-sdk-swift |
| GitHub Stars | Not provided in the source article |
MCP provides a standardized integration layer for external Agent capabilities
At its core, MCP is a standard communication protocol between LLM applications and external tools. It decouples tool discovery, input schemas, invocation results, and the transport layer, so an Agent does not need a custom adapter for every database, file system, or enterprise API.
In Open Agent SDK, the value of MCP is especially clear: built-in tools cover only general-purpose capabilities, while real production environments also need private systems, remote services, and local scripts. MCP brings all of these capabilities into a unified Agent tool pool.
MCP responsibilities are clearly separated
- MCP Server: exposes tools, descriptions, and input structures
- MCP Client: performs the handshake, discovers tools, and executes calls
- Transport layer: carries JSON-RPC and can be swapped across stdio, HTTP, or SSE
public enum McpServerConfig: Sendable, Equatable {
case stdio(McpStdioConfig) // Child process stdin/stdout
case sse(McpTransportConfig) // Server-Sent Events stream
case http(McpTransportConfig) // HTTP request-response
case sdk(McpSdkServerConfig) // Zero-overhead in-process mode
case claudeAIProxy(McpClaudeAIProxyConfig) // ClaudeAI proxy
}This enum defines the SDK’s unified abstraction for multiple MCP transport modes.
Open Agent SDK uses five transport modes to cover local and remote scenarios
The most common option is stdio. The SDK starts a child process and exchanges JSON-RPC messages over stdin/stdout. This works especially well for MCP Servers implemented in Node.js or Python.
let servers: [String: McpServerConfig] = [
"filesystem": .stdio(McpStdioConfig(
command: "npx",
args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
)),
"git": .stdio(McpStdioConfig(
command: "uvx",
args: ["mcp-server-git"],
env: ["GIT_REPO_PATH": "/my/repo"] // Specify the repository path
))
]This example shows how to register local file system and Git capabilities as MCP servers.
Remote MCP services are a better fit for HTTP or SSE
SSE works well when the server needs to push events proactively, while HTTP is ideal for standard request-response interactions. Both can reuse the same underlying transport implementation, with the main difference being whether streaming is enabled.
let remote: [String: McpServerConfig] = [
"remote-tools": .sse(McpTransportConfig(
url: "https://mcp.example.com/sse",
headers: ["Authorization": "Bearer token123"] // Authentication header
)),
"api-tools": .http(McpTransportConfig(
url: "https://mcp.example.com/api"
))
]This configuration shows that remote MCP services can be mounted into an Agent just like ordinary APIs.
The Agent automatically merges MCP tools into the final tool pool
Tool integration is more than establishing a connection. The real challenge is how to merge discovered tools into the set visible to the Agent. The SDK’s assembleFullToolPool() handles this process: it first separates .sdk and external configurations, then connects to servers concurrently, and finally filters and assembles everything into one unified tool pool.
func assembleFullToolPool() async -> ([ToolProtocol], MCPClientManager?) {
let baseTools = options.tools ?? []
guard let mcpServers = options.mcpServers, !mcpServers.isEmpty else {
return (baseTools, nil)
}
// Separate in-process MCP from external MCP
let (sdkTools, externalServers) = await Self.processMcpConfigs(mcpServers)
return (sdkTools, nil)
}The key point in this flow is that MCP is not treated as a side channel. It is elevated to a first-class tool source for the Agent.
MCP tools are wrapped with namespaces to avoid conflicts
External tools are ultimately wrapped as definitions that conform to ToolProtocol, and they follow the naming pattern mcp__{serverName}__{toolName}. For example, read_file from filesystem becomes mcp__filesystem__read_file.
This naming strategy provides two benefits: it prevents collisions with built-in tools, and it helps the model infer the semantic source of the tool directly from the name, improving tool selection accuracy.
Runtime management determines whether an Agent is suitable for long-lived applications
Many Agent applications do not run only once; they stay alive continuously. In that case, connection support alone is not enough. You also need state inspection, reconnection, start/stop controls, and dynamic configuration replacement.
let status = await agent.mcpServerStatus()
for (name, info) in status {
print("\(name): \(info.status.rawValue)") // Print the connection status
print("tools: \(info.tools)") // Print the available tool list
}This code queries the current status of MCP servers and is useful for health checks and operational monitoring.
Dynamically replacing the server set is critical in production
setMcpServers() computes a diff between the old and new configurations, identifies added, removed, and changed items, and rebuilds changed servers after removing them instead of hot-editing live connections.
let result = try await agent.setMcpServers([
"filesystem": .stdio(McpStdioConfig(
command: "npx",
args: ["-y", "@modelcontextprotocol/server-filesystem", "/data"]
)),
"database": .stdio(McpStdioConfig(
command: "python3",
args: ["-m", "my_db_server"] // Register the database MCP service
))
])This example shows that you can change the Agent’s tool integration topology without rebuilding the Agent itself.
InProcessMCPServer enables local tool injection with zero protocol overhead
This is one of the most distinctive design choices in Open Agent SDK. Developers can build tools with defineTool() and then wrap them in InProcessMCPServer. In SDK in-process mode, these tools do not go through JSON-RPC at all. The SDK invokes them directly as function calls.
struct WeatherInput: Codable {
let city: String
}
let weatherTool = defineTool(
name: "get_weather",
description: "Get the current weather for a given city.",
inputSchema: [
"type": "object",
"properties": [
"city": ["type": "string", "description": "The city name"]
],
"required": ["city"]
],
isReadOnly: true
) { (input: WeatherInput, context: ToolContext) -> String in
let data = ["Beijing": "Sunny, 22C", "Tokyo": "Cloudy, 18C"]
return data[input.city] ?? "No data for \(input.city)" // Return the weather result directly
}This example demonstrates how to define a local tool that the Agent can invoke.
In-process mode is a better fit for high-frequency, low-latency tools
If a tool is just a local function, a business rule, or an in-memory data query, in-process mode is better than running a standalone MCP Server. It avoids serialization, inter-process communication, and protocol handshakes, which makes it especially effective for high-call-frequency scenarios.
By contrast, if the capability needs to be reused across languages, processes, or machines, a standard MCP server should take priority over a local wrapper.
The MCP resource mechanism lets Agents not only act, but also read data
MCP does not only define Tools; it also defines Resources. Tools focus on execution, while Resources focus on retrieval. For example, a database service might expose a tool such as query and also expose a resource catalog such as tables.
To support this model, the SDK provides two read-only tools: ListMcpResources and ReadMcpResource. These let an Agent discover resources first and then read specific content by URI. This design works especially well for knowledge bases, file catalogs, and metadata exploration scenarios.
In practice, prioritize naming, fallback behavior, and transport fit
For local command-line tools, prefer stdio. For remote platform services, prefer HTTP or SSE. For local pure-function tools, prefer InProcessMCPServer. Choosing the wrong transport has a direct impact on deployment complexity and system stability.
Also, an MCP server failure should not bring down the entire Agent. Open Agent SDK’s default strategy is that a failed server contributes zero tools while the main loop keeps running. This partial-failure, whole-system-available approach is a strong fit for production systems.
AI Visual Insight: This image is an animated sharing prompt from a blogging platform. It does not contain technical information about the MCP protocol, Agent architecture, or SDK runtime flow, so it offers limited engineering value for understanding this article.
FAQ
Q: When should I choose InProcessMCPServer instead of an external MCP Server?
A: Choose InProcessMCPServer when the tool already exists in the current process, is called frequently, and does not need cross-language reuse. It has zero serialization overhead, lower latency, and a more direct debugging experience.
Q: Why do MCP tools use a name like mcp__server__tool?
A: This naming convention solves tool name collisions and helps the model identify the source from the name itself. The clearer the namespace, the easier it is for the model to choose the right tool.
Q: If an MCP server disconnects, does the entire Agent become unavailable?
A: No. The SDK marks failed servers as failed or pending, while the main Agent continues to run. You can inspect the status with mcpServerStatus() and restore connectivity with reconnectMcpServer().
Key takeaways
This article systematically breaks down how Open Agent SDK integrates MCP in Swift, covering five access modes: stdio, HTTP, SSE, ClaudeAI Proxy, and InProcessMCPServer. It explains the full path from tool discovery and namespace wrapping to runtime management and resource reading.