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

> Understand AI SDK vs MCP Server in Osmosis Agent Toolkit. Integrate AI tools directly as JavaScript objects or via RPC endpoints for flexible agent architectures.

- Repository: [Jon Ator/osmosis-agent-toolkit](https://github.com/jonator/osmosis-agent-toolkit)
- Tags: architecture
- Published: 2026-03-05

---

**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`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/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`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/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:

```typescript
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`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/packages/ai-sdk/src/toolkit.ts) before executing the core logic from [`packages/core/src/toolkit.ts`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/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:

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

```

Remote clients connect via MCP protocol:

```typescript
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`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/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`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/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`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/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`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/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.