AI SDK vs MCP Server in Osmosis Agent Toolkit: Integration Architecture Guide

The AI SDK package wraps Osmosis tools as in-process JavaScript objects for direct framework integration, while the MCP server exposes them as remote RPC endpoints via the Model Context Protocol for distributed agent architectures.

The jonator/osmosis-agent-toolkit repository distributes its core DeFi automation primitives through two distinct integration patterns. When deciding between the AI SDK versus MCP server, you choose between embedding tools directly within your application process or deploying them as discoverable network services that other agents can invoke remotely.

Architectural Overview: In-Process vs. Remote Execution

AI SDK Package: Direct Framework Integration

Located in packages/ai-sdk/src/toolkit.ts, the OsmosisAgentToolkit class extends the core toolkit and exposes a tools getter that returns AI SDK-compatible tool objects. These wrappers handle parameter validation internally and return plain JavaScript values directly to your application code.

This approach runs in-process, requiring only the ai NPM package and the core toolkit dependency. Tools execute as direct function calls—await toolkit.swapQuoteInGivenOutTool.call(params)—without network overhead or serialization layers.

MCP Server: Protocol-Based Service Layer

The OsmosisAgentServer class in packages/mcp/src/server.ts extends the base McpServer and registers each core tool using this.tool(...). Unlike the AI SDK wrapper, this implementation starts a standalone Node.js process that listens for incoming JSON-RPC requests over the Model Context Protocol.

Clients must use an MCP client library to invoke tools remotely. The server wraps all return values in MCP-specific ToolCallback objects—specifically using createTextOutput to JSON-encode results—adding a serialization layer between the core business logic and the consumer.

Implementation Examples

Using the AI SDK for Single-Process Agents

The AI SDK package integrates seamlessly with frameworks like Vercel AI SDK. Import OsmosisAgentToolkit and pass the allTools accessor to your model configuration:

import { createAI } from '@ai-sdk/react'
import { OsmosisAgentToolkit } from '@osmosis-agent-toolkit/ai-sdk'

const toolkit = new OsmosisAgentToolkit(process.env.MNEMONIC!)

const model = createAI({
  model: 'gpt-4o-mini',
  tools: toolkit.allTools,  // Array of AI SDK Tool objects
})

const result = await model.run(
  'What is the best swap quote to receive 100 USDC using OSMO?'
)

In this pattern, the model invokes swapQuoteInGivenOutTool.call(...) directly within the same process, with the wrapper handling validation in packages/ai-sdk/src/toolkit.ts before executing the core logic from packages/core/src/toolkit.ts.

Deploying the MCP Server for Distributed Access

Deploy the MCP server as a containerized service using the provided packages/mcp/Dockerfile. The server exposes tools as network endpoints:

docker build -t osmosis-mcp ./packages/mcp
docker run -e MNEMONIC=your-mnemonic -p 3000:3000 osmosis-mcp

Remote clients connect via MCP protocol:

import { McpClient } from '@modelcontextprotocol/sdk/client/mcp.js'

const client = new McpClient({ url: 'http://localhost:3000' })

const result = await client.callTool(
  'swapQuoteInGivenOutTool',
  { tokenIn: 'uosmo', tokenOut: 'uusdc', amountOut: '1000000' }
)

const quote = JSON.parse(result.content[0].text)

The server implementation in packages/mcp/src/server.ts (lines 19-55) registers each tool and wraps outputs using createTextOutput, converting raw objects to JSON-encoded text for MCP compliance.

Critical Distinctions

• Runtime Requirements: The AI SDK runs within your application process with no additional infrastructure. The MCP server requires a separate Node.js process, typically containerized, with port exposure for RPC communication.

• Invocation Style: AI SDK uses direct method calls on tool objects. MCP requires JSON-RPC payloads sent via McpClient.callTool(), with the server handling request routing.

• Data Serialization: AI SDK returns raw JavaScript objects, numbers, and strings. The MCP server returns structured ToolCallback objects where results live in content[0].text as JSON strings.

• Deployment Model: Include @osmosis-agent-toolkit/ai-sdk as a standard NPM dependency bundled with your frontend or backend. Run @osmosis-agent-toolkit/mcp as a standalone service or Docker container for multi-agent ecosystems.

Summary

• The AI SDK package (packages/ai-sdk) provides in-process tool wrappers for direct integration with JavaScript AI frameworks like Vercel AI SDK.
• The MCP server (packages/mcp) exposes the same core functionality via the Model Context Protocol for remote, cross-process agent communication.
• Both implementations delegate to OsmosisAgentToolkit in packages/core/src/toolkit.ts, ensuring identical business logic regardless of integration path.
• Choose the AI SDK for single-process applications requiring low latency and simple bundling; select the MCP server for service-oriented architectures where multiple agents must share tools over a network.

Frequently Asked Questions

Can I use both the AI SDK and MCP server in the same project?

Yes. Both packages import from the same @osmosis-agent-toolkit/core dependency, so you can embed tools directly via the AI SDK for local operations while simultaneously exposing them via MCP for remote agent consumption. The core toolkit in packages/core/src/toolkit.ts ensures consistent behavior across both interfaces.

Does the MCP server support all tools available in the AI SDK?

Yes. The OsmosisAgentServer class in packages/mcp/src/server.ts registers every tool exposed by the core OsmosisAgentToolkit. The registration loop ensures feature parity, though outputs are necessarily JSON-serialized through createTextOutput to comply with MCP specifications.

Which approach offers better performance for high-frequency trading?

The AI SDK package offers lower latency for high-frequency operations because it executes tools in-process without network serialization or JSON-RPC overhead. The MCP server's remote procedure calls introduce additional latency from HTTP transport and JSON.stringify/JSON.parse operations in the ToolCallback wrapper.

How do I secure the mnemonic when using the MCP server?

The MCP server accepts the mnemonic via environment variables, as shown in the Docker example docker run -e MNEMONIC=.... For production deployments, use a secrets manager to inject this variable and ensure the packages/mcp/Dockerfile runs the container in an isolated network segment, as the server must maintain wallet access to sign transactions on behalf of connected agents.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}