✨ Features

1<div align="center">
2  <img src="docs/static/img/mcp-ts-banner.svg" alt="MCP-TS Banner" width="100%" style="max-width: 1200px;" />
3</div>
4 
5<div align="center">
6  <a href="https://zonlabs.github.io/mcp-ts/#ag-ui-demo">
7    <em>Watch AG-UI + LangChain demo</em>
8  </a>
9</div>
10<br />
11 
12 
13<div align="center">
14 
15| *Supported Frameworks* | *Agent Frameworks and Protocol* | *Storage Backends* |
16| :---: | :---: | :---: |
17| <img src="docs/static/img/framework/next.svg" width="35" height="35" /> <img src="docs/static/img/framework/node.svg" width="35" height="35" /> <img src="docs/static/img/framework/react.svg" width="35" height="35" /> <img src="docs/static/img/framework/vue.svg" width="35" height="35" /> <img src="docs/static/img/framework/express.svg" width="35" height="35" /> | <img src="docs/static/img/framework/vercel.svg" width="35" height="35" /> <img src="docs/static/img/agent-framework/langchain.svg" width="35" height="35" /> <img src="docs/static/img/agent-framework/mastra.svg" width="35" height="35" /> <img src="docs/static/img/agent-framework/agui.webp" width="35" height="35" /> | <img src="docs/static/img/storage-backend/redis.svg" width="35" height="35" /> <img src="docs/static/img/storage-backend/sqlite.svg" width="35" height="35" /> <img src="docs/static/img/storage-backend/filesystem.svg" width="35" height="35" /> <img src="docs/static/img/storage-backend/memory.svg" width="35" height="35" /> |
18 
19</div>
20 
21<p align="center">
22  <a href="https://www.npmjs.com/package/@mcp-ts/sdk">
23    <img src="https://img.shields.io/npm/v/@mcp-ts/sdk?style=flat-square&logo=npm&logoColor=white&label=%40mcp-ts%2Fsdk&color=dc2626" alt="npm version" />
24  </a>
25  <a href="https://zonlabs.github.io/mcp-ts/">
26    <img src="https://img.shields.io/badge/docs-website-2563eb?style=flat-square&logo=readthedocs&logoColor=white" alt="Documentation" />
27  </a>
28  <a href="https://opensource.org/licenses/MIT">
29    <img src="https://img.shields.io/badge/license-MIT-84cc16?style=flat-square" alt="License: MIT" />
30  </a>
31</p>
32 
33 
34 
35## ✨ Features
36 
37- **SSE** - Server-Sent Events for connection state and observability updates
38- **Flexible Storage** - Redis, SQLite, File System, or In-Memory backends
39- **Serverless** - Works in serverless environments (Vercel, AWS Lambda, etc.)
40- **React Hook** - `useMcp` hook for easy React integration
41- **Vue Composable** - `useMcp` composable for Vue applications
42- **MCP Protocol** - Support for tools, prompts, and resources
43- **Agent Adapters** - Built-in adapters for AI SDK, LangChain, Mastra, and AG-UI
44- **MCP Apps Extension (SEP-1865)** - Interactive UI-driven tool interfaces
45 
46## 🧪 Examples
47 
48Check out working examples demonstrating the MCP Apps extension and agent integrations in the [examples/agents](examples/agents) directory.
49 
50> Examples MCP Apps referred from [modelcontextprotocol/ext-apps](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples)
51 
52<div align="center">
53  <table cellspacing="5" cellpadding="0">
54    <tr>
55      <td width="50%">
56        <img src="docs/static/img/mcp-apps-img-1.png" alt="MCP Apps 1" width="100%" />
57      </td>
58      <td width="50%">
59        <img src="docs/static/img/mcp-apps-img-2.png" alt="MCP Apps 2" width="100%" />
60      </td>
61    </tr>
62  </table>
63  <p><em>Interactive UIs for MCP tools</em></p>
64</div>
65 
66## 💡 Inspiration
67 
68> I got the idea for `@mcp-ts` while working on 🌐 **[MCP Assistant](https://mcp-assistant.in)**.
69As the project grew, I had a few problems: storage, using different AI frameworks like LangGraph and ADK for different use cases, and figuring out how to get progressive SSE updates at each step so I could see what was happening.
70So with that idea in mind, I built this SDK to make setup easier and keep the user experience smooth.
71That’s how `@mcp-ts` started.
72 
73<br/>
74 
75<div align="center">
76  <img src="docs/static/img/mcp-assistant.png" alt="MCP Assistant" width="100%" />
77</div>
78 
79<br/>
80 
81## 📦 Installation
82 
83```bash
84npm install @mcp-ts/sdk
85```
86 
87The package supports multiple storage backends out of the box:
88- **Memory** (default, no setup required)
89- **File** (local persistence)
90- **SQLite** (fast local persistence, requires `npm install better-sqlite3`)
91- **Redis** (production-ready, requires `npm install ioredis`)
92 
93## 🚀 Quick Start
94 
95### 🖥️ Server-Side (Next.js)
96 
97```typescript
98// app/api/mcp/route.ts
99import { createNextMcpHandler } from '@mcp-ts/sdk/server';
100 
101export const dynamic = 'force-dynamic';
102export const runtime = 'nodejs';
103 
104export const { GET, POST } = createNextMcpHandler({
105  authenticate: () => {
106    //  your logic here
107  }
108});
109```
110 
111### 🎯 Client-Side (React)
112 
113```typescript
114'use client';
115 
116import { useMcp } from '@mcp-ts/sdk/client/react';
117 
118function App() {
119  const { connections, connect } = useMcp({
120    url: '/api/mcp',
121    identity: 'user-123',
122  });
123 
124  return (
125    <div className="flex flex-col items-center gap-4">
126      <button
127        onClick={() =>
128          connect({
129            serverId: 'my-server',
130            serverName: 'My MCP Server',
131            serverUrl: 'https://mcp.example.com',
132            callbackUrl: `${window.location.origin}/callback`,
133          })
134        }
135      >
136        Connect
137      </button>
138      {connections.map((conn) => (
139        <div key={conn.sessionId}>
140          <h3>{conn.serverName}</h3>
141          <p>State: {conn.state}</p>
142          <p>Tools: {conn.tools.length}</p>
143        </div>
144      ))}
145    </div>
146  );
147}
148```
149 
150### 🔌 Adapters
151 
152Integrating with agent frameworks is simple using built-in adapters.
153 
154<details>
155<summary>Vercel AI SDK</summary>
156 
157```typescript
158// app/api/chat/route.ts
159import { MultiSessionClient } from '@mcp-ts/sdk/server';
160import { AIAdapter } from '@mcp-ts/sdk/adapters/ai';
161import { streamText } from 'ai';
162import { openai } from '@ai-sdk/openai';
163 
164export async function POST(req: Request) {
165  const { messages, identity } = await req.json();
166  const client = new MultiSessionClient(identity);
167 
168  try {
169    await client.connect();
170    const tools = await AIAdapter.getTools(client);
171    const result = streamText({
172      model: openai('gpt-4'),
173      messages,
174      tools,
175      onFinish: async () => {
176        await client.disconnect();
177      }
178    });
179    return result.toDataStreamResponse();
180  } catch (error) {
181    await client.disconnect();
182    throw error;
183  }
184}
185```
186 
187</details>
188 
189<details>
190<summary>Agui Adapter</summary>
191 
192```typescript
193import { MultiSessionClient } from '@mcp-ts/sdk/server';
194import { AguiAdapter } from '@mcp-ts/sdk/adapters/agui-adapter';
195 
196const client = new MultiSessionClient("user_123");
197await client.connect();
198 
199const adapter = new AguiAdapter(client);
200const tools = await adapter.getTools();
201```
202 
203</details>
204 
205<details>
206<summary>Mastra Adapter</summary>
207 
208```typescript
209import { MultiSessionClient } from '@mcp-ts/sdk/server';
210import { MastraAdapter } from '@mcp-ts/sdk/adapters/mastra-adapter';
211 
212const client = new MultiSessionClient("user_123");
213await client.connect();
214 
215const tools = await MastraAdapter.getTools(client);
216```
217 
218</details>
219 
220### 🧩 AG-UI Middleware
221 
222Execute MCP tools server-side when using remote agents (LangGraph, AutoGen, etc.):
223 
224<details>
225<summary>View AG-UI (Agent Middleware)</summary>
226 
227```typescript
228import { HttpAgent } from "@ag-ui/client";
229import { AguiAdapter } from "@mcp-ts/sdk/adapters/agui-adapter";
230import { createMcpMiddleware } from "@mcp-ts/sdk/adapters/agui-middleware";
231 
232// Connect to MCP servers
233const { MultiSessionClient } = await import("@mcp-ts/sdk/server");
234const client = new MultiSessionClient("user_123");
235await client.connect();
236 
237// Create adapter and get tools
238const adapter = new AguiAdapter(client);
239const mcpTools = await adapter.getTools();
240 
241// Create agent with middleware
242const agent = new HttpAgent({ url: "http://localhost:8000/agent" });
243agent.use(createMcpMiddleware({
244  toolPrefix: 'server-',
245  tools: mcpTools,
246}));
247```
248 
249</details>
250 
251The middleware intercepts tool calls from remote agents, executes MCP tools server-side, and returns results back to the agent.
252 
253### 🛠️ MCP Apps (SEP-1865)
254 
255Render interactive UIs for your tools using the `useMcpApps` hook.
256 
257<details>
258<summary>View MCP Apps</summary>
259 
260```typescript
261import { useRenderToolCall } from "@copilotkit/react-core";
262import { useMcpApps } from "@mcp-ts/sdk/client/react";
263import { useMcpContext } from "./mcp";
264 
265export function ToolRenderer() {
266  const { mcpClient } = useMcpContext();
267  const { getAppMetadata, McpAppRenderer } = useMcpApps(mcpClient);
268 
269  useRenderToolCall({
270    name: "*",
271    render: ({ name, args, result, status }) => {
272      const metadata = getAppMetadata(name);
273      
274      if (!metadata) return null;
275 
276      return (
277        <McpAppRenderer
278          metadata={metadata}
279          input={args}
280          result={result}
281          status={status}
282          sseClient={mcpClient.sseClient}
283        />
284      );
285    },
286  });
287 
288  return null;
289}
290```
291 
292</details>
293 
294## 📚 Documentation
295 
296Full documentation is available at: **[Docs](https://zonlabs.github.io/mcp-ts/)**
297 
298### 🗂️ Topics Covered:
299 
300- **[Getting Started](https://zonlabs.github.io/mcp-ts/docs/)** - Quick setup and overview
301- **[Installation](https://zonlabs.github.io/mcp-ts/docs/installation)** - Detailed installation guide
302- **[Storage Backends](https://zonlabs.github.io/mcp-ts/docs/storage-backends)** - Redis, File, Memory options
303- **[Next.js Integration](https://zonlabs.github.io/mcp-ts/docs/nextjs)** - Complete Next.js examples
304- **[React Hook Guide](https://zonlabs.github.io/mcp-ts/docs/react-hook)** - Using the useMcp hook
305- **[API Reference](https://zonlabs.github.io/mcp-ts/docs/api-reference)** - Complete API documentation
306 
307## ⚙️ Environment Setup
308 
309The library supports multiple storage backends. You can explicitly select one using `MCP_TS_STORAGE_TYPE` or rely on automatic detection.
310 
311**Supported Types:** `redis`, `sqlite`, `file`, `memory`.
312 
313### 🧷 Configuration Examples
314 
3151.  **<img src="docs/static/img/storage-backend/redis.svg" width="20" height="20" align="center" /> Redis** (Recommended for production)
316    ```bash
317    MCP_TS_STORAGE_TYPE=redis
318    REDIS_URL=redis://localhost:6379
319    ```
320 
3212.  **<img src="docs/static/img/storage-backend/sqlite.svg" width="20" height="20" align="center" /> SQLite** (Fast & Persistent)
322    ```bash
323    MCP_TS_STORAGE_TYPE=sqlite
324    # Optional path
325    MCP_TS_STORAGE_SQLITE_PATH=./sessions.db
326    ```
327 
3283.  **<img src="docs/static/img/storage-backend/filesystem.svg" width="20" height="20" align="center" /> File System** (Great for local dev)
329    ```bash
330    MCP_TS_STORAGE_TYPE=file
331    MCP_TS_STORAGE_FILE=./sessions.json
332    ```
333 
3344.  **<img src="docs/static/img/storage-backend/memory.svg" width="20" height="20" align="center" /> In-Memory** (Default for testing)
335    ```bash
336    MCP_TS_STORAGE_TYPE=memory
337    ```
338 
339## 🏗️ Architecture
340 
341`@mcp-ts/sdk` supports two common runtime topologies: direct SSE from browser clients, and outbound bridge connectivity for local agents.
342 
343 
344```mermaid
345graph LR
346    subgraph Direct["Direct SDK Flow (SSE)"]
347        UI[Browser UI]
348        Hook[useMcp Hook]
349        API[Next.js /api/mcp]
350        Mgr[MultiSessionClient]
351        Store[(Redis/File/Memory)]
352        MCP[MCP Servers]
353 
354        UI <--> Hook
355        Hook -- "HTTP RPC" --> API
356        API --> Mgr
357        Mgr -- "SSE events" --> Hook
358        Mgr <--> Store
359        Mgr <--> MCP
360    end
361 
362    subgraph Bridge["Remote Bridge Flow (mcp-local-agent)"]
363        direction TB
364        Spacer[" "]
365        Agent[Local Agent Runtime]
366        Remote[Remote Bridge Server]
367        LocalMcp[Local MCP Servers]
368 
369        Spacer --- Agent
370        Agent -- "WSS /connect (outbound)" --> Remote
371        Agent <--> LocalMcp
372        style Spacer fill:transparent,stroke:transparent,color:transparent
373    end
374```
375 
376- **Direct SDK flow**: Browser clients use `useMcp` over HTTP + SSE to a server route backed by `MultiSessionClient`.
377- **Bridge flow**: `mcp-local-agent` keeps an outbound authenticated WebSocket to a remote bridge and forwards tool calls to local MCP servers.
378- **Storage**: Session state and connection metadata persist in Redis, File, SQLite, or Memory backends.
379 
380> [!NOTE]
381> This package (`@mcp-ts/sdk`) provides a unified MCP client with support for adapters and storage backends such as AI SDK, Mastra, LangChain, and Redis.
382> Adapters and storage backends are loaded via **optional peer dependencies** and must be installed independently. This ensures your application only includes the integrations you explicitly choose, keeping bundle size small and avoiding unnecessary dependencies.
383> The SDK includes built-in support for **Memory** and **File** storage, while additional backends (such as Redis) and adapters can be added without impacting users who don’t need them.
384 
385For more details, refer to the documentation and follow the **installation guide for each adapter or storage backend**.
386 
387- [AI SDK Installation Guide](https://zonlabs.github.io/mcp-ts/docs/adapters#installation)
388- [Mastra Installation Guide](https://zonlabs.github.io/mcp-ts/docs/adapters#installation)
389- [LangChain Installation Guide](https://zonlabs.github.io/mcp-ts/docs/adapters#installation)
390- [Redis Storage Installation Guide](https://zonlabs.github.io/mcp-ts/docs/storage-backends#-redis-production)
391 
392 
393## 🤝 Contributing
394 
395Contributions are welcome! Please read [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines on how to contribute.
396 
397 
398<br />
399 
400<p align="center">
401  <em> Thanks for visiting ✨ @mcp-ts!</em><br><br>
402  <img src="https://visitor-badge.laobi.icu/badge?page_id=zonlabs.mcp-ts&style=for-the-badge&color=00d4ff" alt="Views">
403</p>
404 
405