@mcp-ts/sdk

v2.3.4

Published

8 days ago

A lightweight MCP (Model Context Protocol) client library for JavaScript and cross-runtime environments, supporting MCP Apps in host applications and multiple storage backends (Memory, File, Redis, Supabase, Neon).

0High
0Medium
0Low

mcp-ts

mcp model-context-protocol oauth redis sse server-sent-events serverless react hook anthropic claude

📖 Table of Contents

📦 Packages

✨ Features

Most features are available out-of-the-box in the TypeScript SDK:

SSE - Server-Sent Events for connection state and observability updates
Flexible Storage - Redis, SQLite, File System, or In-Memory backends
Serverless - Works in serverless environments (Vercel, AWS Lambda, etc.)
React Hook - useMcp hook for easy React integration
Vue Composable - useMcp composable for Vue applications
MCP Protocol - Support for tools, prompts, and resources
Agent Adapters - Built-in adapters for AI SDK, LangChain, Mastra, and AG-UI
MCP Apps Extension (SEP-1865) - Interactive UI-driven tool interfaces

🧪 Examples

Check out working examples demonstrating the MCP Apps extension and agent integrations in the examples/agents directory.

Examples MCP Apps referred from modelcontextprotocol/ext-apps

💡 Inspiration

I got the idea for @mcp-ts while working on 🌐 MCP Assistant. As 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. So with that idea in mind, I built this SDK to make setup easier and keep the user experience smooth. That’s how @mcp-ts started.

🛠️ SDK Setup (@mcp-ts/sdk)

📦 Installation

npm install @mcp-ts/sdk

The SDK supports multiple storage backends out of the box:

Memory (default, no setup required)
File (local persistence)
SQLite (fast local persistence, requires npm install better-sqlite3)
Redis (production-ready, requires npm install ioredis)

🚀 Quick Start

🖥️ Server-Side (Next.js)

// app/api/mcp/route.ts
import { createNextMcpHandler } from '@mcp-ts/sdk/server';

export const dynamic = 'force-dynamic';
export const runtime = 'nodejs';

export const { GET, POST } = createNextMcpHandler({
  authenticate: () => {
    //  your logic here
  }
});

🎯 Client-Side (React)

'use client';

import { useMcp } from '@mcp-ts/sdk/client/react';

function App() {
  const { connections, connect } = useMcp({
    url: '/api/mcp',
    userId: 'user-123',
  });

  return (
    <div className="flex flex-col items-center gap-4">
      <button
        onClick={() =>
          connect({
            serverId: 'my-server',
            serverName: 'My MCP Server',
            serverUrl: 'https://mcp.example.com',
            callbackUrl: `${window.location.origin}/callback`,
          })
        }
      >
        Connect
      </button>
      {connections.map((conn) => (
        <div key={conn.sessionId}>
          <h3>{conn.serverName}</h3>
          <p>State: {conn.state}</p>
          <p>Tools: {conn.tools.length}</p>
        </div>
      ))}
    </div>
  );
}

🔌 Adapters

Integrating with agent frameworks is simple using built-in adapters.

// app/api/chat/route.ts
import { MultiSessionClient } from '@mcp-ts/sdk/server';
import { AIAdapter } from '@mcp-ts/sdk/adapters/ai';
import { streamText } from 'ai';
import { openai } from '@ai-sdk/openai';

export async function POST(req: Request) {
  const { messages, userId } = await req.json();
  const client = new MultiSessionClient(userId);

  try {
    await client.connect();
    const tools = await AIAdapter.getTools(client);
    const result = streamText({
      model: openai('gpt-4'),
      messages,
      tools,
      onFinish: async () => {
        await client.disconnect();
      }
    });
    return result.toDataStreamResponse();
  } catch (error) {
    await client.disconnect();
    throw error;
  }
}

import { MultiSessionClient } from '@mcp-ts/sdk/server';
import { AguiAdapter } from '@mcp-ts/sdk/adapters/agui-adapter';

const client = new MultiSessionClient("user_123");
await client.connect();

const adapter = new AguiAdapter(client);
const tools = await adapter.getTools();

import { MultiSessionClient } from '@mcp-ts/sdk/server';
import { MastraAdapter } from '@mcp-ts/sdk/adapters/mastra-adapter';

const client = new MultiSessionClient("user_123");
await client.connect();

const tools = await MastraAdapter.getTools(client);

🧩 AG-UI Middleware

Execute MCP tools server-side when using remote agents (LangGraph, AutoGen, etc.):

import { HttpAgent } from "@ag-ui/client";
import { AguiAdapter } from "@mcp-ts/sdk/adapters/agui-adapter";
import { createMcpMiddleware } from "@mcp-ts/sdk/adapters/agui-middleware";

// Connect to MCP servers
const { MultiSessionClient } = await import("@mcp-ts/sdk/server");
const client = new MultiSessionClient("user_123");
await client.connect();

// Create adapter and get tools
const adapter = new AguiAdapter(client);
const mcpTools = await adapter.getTools();

// Create agent with middleware
const agent = new HttpAgent({ url: "http://localhost:8000/agent" });
agent.use(createMcpMiddleware({
  toolPrefix: 'server-',
  tools: mcpTools,
}));

The middleware intercepts tool calls from remote agents, executes MCP tools server-side, and returns results back to the agent.

🛠️ MCP Apps (SEP-1865)

Render interactive UIs for your tools using the useMcpApps hook.

import { useRenderToolCall } from "@copilotkit/react-core";
import { useMcpApps } from "@mcp-ts/sdk/client/react";
import { useMcpContext } from "./mcp";

export function ToolRenderer() {
  const { mcpClient } = useMcpContext();
  const { McpAppRenderer } = useMcpApps(mcpClient);

  useRenderToolCall({
    name: "*",
    render: ({ name, args, result, status }) => (
      <McpAppRenderer
        name={name}
        input={args}
        result={result}
        status={status}
      />
    ),
  });

  return null;
}

📚 Documentation

Full documentation is available at: Docs

🗂️ Topics Covered:

Getting Started - Quick setup and overview
Installation - Detailed installation guide
Storage Backends - Redis, File, Memory options
Next.js Integration - Complete Next.js examples
React Hook Guide - Using the useMcp hook
API Reference - Complete API documentation

⚙️ Environment Setup

The library supports multiple storage backends. You can explicitly select one using MCP_TS_STORAGE_TYPE or rely on automatic detection.

Supported Types: redis, supabase, neon, sqlite, file, memory.

🧷 Configuration Examples

Redis (Recommended for production)

MCP_TS_STORAGE_TYPE=redis
REDIS_URL=redis://localhost:6379

SQLite (Fast & Persistent)

MCP_TS_STORAGE_TYPE=sqlite
# Optional path
MCP_TS_STORAGE_SQLITE_PATH=./sessions.db

Neon (Serverless Postgres)

MCP_TS_STORAGE_TYPE=neon
NEON_DATABASE_URL=postgresql://user:[email protected]/dbname?sslmode=verify-full&channel_binding=require

File System (Great for local dev)

MCP_TS_STORAGE_TYPE=file
MCP_TS_STORAGE_FILE=./sessions.json

In-Memory (Default for testing)
```
MCP_TS_STORAGE_TYPE=memory
```

🐍 Gateway Setup (mcpassistant-gateway)

The MCP Gateway is a Python-based bridge that allows local MCP servers to be accessed by remote applications via an outbound connection. This is useful for providing local context (like your filesystem) to a hosted AI agent.

📦 Installation

pip install mcpassistant-gateway

🚀 Usage

You can run the gateway using uvx or pip:

# Run the interactive menu
uvx mcpassistant-gateway menu

# Run the bridge directly
uvx mcpassistant-gateway run --name "local-files"

🏗️ Architecture

The MCP Toolkit supports two common runtime topologies:

graph LR
    subgraph Direct["Direct SDK Flow (TypeScript)"]
        UI[Browser UI]
        Hook[useMcp Hook]
        API[Next.js /api/mcp]
        Mgr[MultiSessionClient]
        Store[(Redis/File/Memory)]
        MCP[MCP Servers]

        UI <--> Hook
        Hook -- "HTTP RPC" --> API
        API --> Mgr
        Mgr -- "SSE events" --> Hook
        Mgr <--> Store
        Mgr <--> MCP
    end

    subgraph Bridge["Remote Bridge Flow (Python)"]
        direction TB
        Spacer[" "]
        Agent[mcpassistant-gateway]
        Remote[Remote Bridge Server]
        LocalMcp[Local MCP Servers]

        Spacer --- Agent
        Agent -- "WSS /connect (outbound)" --> Remote
        Agent <--> LocalMcp
        style Spacer fill:transparent,stroke:transparent,color:transparent
    end

Direct SDK flow: Browser clients use useMcp over HTTP + SSE to a server route backed by MultiSessionClient.
Bridge flow: mcpassistant-gateway keeps an outbound authenticated WebSocket to a remote bridge and forwards tool calls to local MCP servers.
Storage: Session state and connection metadata persist in Redis, File, SQLite, or Memory backends.

[!NOTE] 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. 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. 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.

For more details, refer to the documentation and follow the installation guide for each adapter or storage backend.

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines on how to contribute.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

📖 Table of Contents

📦 Packages

✨ Features

🧪 Examples

💡 Inspiration

🛠️ SDK Setup (@mcp-ts/sdk)

📦 Installation

🚀 Quick Start

🖥️ Server-Side (Next.js)

🎯 Client-Side (React)

🔌 Adapters

🧩 AG-UI Middleware

🛠️ MCP Apps (SEP-1865)

📚 Documentation

🗂️ Topics Covered:

⚙️ Environment Setup

🧷 Configuration Examples

🐍 Gateway Setup (mcpassistant-gateway)

📦 Installation

🚀 Usage

🏗️ Architecture

🤝 Contributing