@ubuligan/client

A thin, ergonomic DX layer over the MCP SDK Client. You get transport selection (stdio or Streamable HTTP), auth, retry and logging from a single config object — and the raw SDK client is always reachable via .raw for anything advanced.

Part of the MCP Toolkit.

Install

npm install @ubuligan/client

Node only. For the browser/React, use @ubuligan/react (stdio needs child_process, which doesn't exist in the browser).

Quick start

import { createMCPClient } from "@ubuligan/client";

// Connects immediately and returns a ready client.
const client = await createMCPClient({
  transport: { type: "http", url: "http://localhost:3000/mcp" },
  logger: "info",
});

const { tools } = await client.listTools();
const result = await client.callTool("add", { a: 2, b: 3 });
console.log(result.content);

await client.close();

Connecting to a local stdio server

const client = await createMCPClient({
  transport: { type: "stdio", command: "node", args: ["dist/index.js"] },
});

Auth + retry

const client = await createMCPClient({
  transport: { type: "http", url: "https://api.example.com/mcp" },
  auth: { type: "bearer", token: () => getFreshToken() }, // sync or async
  retry: { retries: 5, minDelayMs: 250 },
  logger: "debug",
});

API

createMCPClient(options): Promise<MCPClient>

Construct and connect in one call. Same options as the MCPClient constructor.

new MCPClient(options)

Construct without connecting. Call await client.connect() yourself.

Options

| Field | Type | Notes | | --- | --- | --- | | transport | TransportConfig | Required. { type: "stdio", command, args? } or { type: "http", url }. | | auth | AuthConfig | Applied to HTTP transports. Bearer or custom headers; values may be async. | | retry | RetryOptions | Wraps every request. { retries: 1 } disables. | | logger | Logger \| LogLevel | A level string ("info") uses the built-in console logger. | | name, version | string | Client identity advertised to the server. |

Methods — connect(), close(), listTools(), callTool(name, args?), listResources(), readResource(uri), listPrompts(), getPrompt(name, args?). Every method is retry- and log-wrapped. client.raw is the underlying SDK Client.

License

MIT