MCP Client

The mcpfy client API provides a simple way to connect to MCP servers and interact with their tools, prompts, and resources. It is designed around three main concepts:

MCPClient — manages connections to one or more configured MCP servers.
MCPSession — represents an active connection to a specific MCP server.
Connectors — handle the underlying transport, currently supporting stdio and HTTP.

The client API is intentionally lightweight and forwards MCP operations to the official Model Context Protocol TypeScript SDK.

Installation

npm install mcpfy-sdk

import { MCPClient } from "mcpfy-sdk/client";

Or import all client utilities:

import {
  MCPClient,
  MCPSession,
  StdioConnector,
  HttpConnector,
  createConnectorFromConfig,
} from "mcpfy-sdk/client";

Architecture

MCPClient
   │
   ├── Server Configuration
   │       ├── Stdio configuration
   │       └── HTTP configuration
   │
   ├── createSession()
   │
   ▼
MCPSession
   │
   ▼
BaseConnector
   │
   ├── StdioConnector
   │       └── StdioClientTransport
   │
   └── HttpConnector
           └── StreamableHTTPClientTransport

Responsibilities

Component	Responsibility
`MCPClient`	Manages multiple named MCP server connections
`MCPSession`	Provides operations for one connected server
`BaseConnector`	Common connection and MCP operation layer
`StdioConnector`	Connects through stdio
`HttpConnector`	Connects through HTTP
`createConnectorFromConfig()`	Selects connector from configuration

MCPClient

MCPClient is the primary entry point.

import { MCPClient } from "mcpfy-sdk/client";

Configuration

interface MCPClientConfig {
  mcpServers: Record<string, ServerConfig>;
}

Example

const client = new MCPClient({
  mcpServers: {
    calculator: {
      command: "node",
      args: ["calculator-server.js"],
    },

    weather: {
      url: "http://localhost:3000/mcp",
    },
  },
});

Creating a Session

const session = await client.createSession("calculator");

The method:

Checks existing sessions
Looks up configuration
Creates connector
Connects to MCP server
Creates MCPSession
Stores session
Returns session

Creating All Sessions

const sessions = await client.createAllSessions();

const calculator = sessions.calculator;
const weather = sessions.weather;

Sessions are created concurrently.

Getting a Session

const session = client.getSession("calculator");

Returns:

MCPSession | undefined

Closing Sessions

await client.closeAllSessions();

Example:

try {
  const session = await client.createSession("calculator");

  const result = await session.callTool("add", {
    a: 10,
    b: 20,
  });

  console.log(result);
} finally {
  await client.closeAllSessions();
}

Server Configuration

type ServerConfig =
  | {
      command: string;
      args?: string[];
      env?: Record<string, string>;
      cwd?: string;
    }
  | {
      url: string;
      headers?: Record<string, string>;
      authToken?: string;
      authProvider?: OAuthClientProvider;
    };

Stdio Server Example

const client = new MCPClient({
  mcpServers: {
    localServer: {
      command: "node",
      args: ["server.js"],
    },
  },
});

Advanced Example

const client = new MCPClient({
  mcpServers: {
    database: {
      command: "node",
      args: ["database-server.js"],
      env: {
        DATABASE_URL: "postgresql://localhost/mydb",
      },
      cwd: "./servers",
    },
  },
});

HTTP Server Example

const client = new MCPClient({
  mcpServers: {
    remoteServer: {
      url: "http://localhost:3000/mcp",
    },
  },
});

Custom Headers

const client = new MCPClient({
  mcpServers: {
    remoteServer: {
      url: "https://example.com/mcp",
      headers: {
        "X-API-Key": "your-api-key",
      },
    },
  },
});

Bearer Authentication

const client = new MCPClient({
  mcpServers: {
    protectedServer: {
      url: "https://example.com/mcp",
      authToken: "your-access-token",
    },
  },
});

Automatically sends:

Authorization: Bearer your-access-token

OAuth

const client = new MCPClient({
  mcpServers: {
    protectedServer: {
      url: "https://example.com/mcp",
      authProvider: oauthProvider,
    },
  },
});

MCPSession

Create a session:

const session = await client.createSession("calculator");

A session provides access to:

Tools
Prompts
Resources
Resource contents

Tools

List Tools

const tools = await session.listTools();

for (const tool of tools) {
  console.log(tool.name);
}

Call Tool

const result = await session.callTool("add", {
  a: 10,
  b: 20,
});

console.log(result);

Prompts

List Prompts

const prompts = await session.listPrompts();

Get Prompt

const result = await session.getPrompt("summarize", {
  topic: "artificial intelligence",
});

Resources

List Resources

const resources = await session.listResources();

Read Resource

const result = await session.readResource(
  "file:///example/data.txt"
);

console.log(result);

Close Session

await session.close();

Connectors

StdioConnector

import { StdioConnector } from "mcpfy-sdk/client";

const connector = new StdioConnector({
  command: "node",
  args: ["server.js"],
});

HttpConnector

import { HttpConnector } from "mcpfy-sdk/client";

const connector = new HttpConnector({
  url: "http://localhost:3000/mcp",
});

Supports:

{
  url: "https://example.com/mcp",
  headers: {
    "X-API-Key": "secret",
  }
}

Bearer Auth:

{
  url: "https://example.com/mcp",
  authToken: "access-token",
}

OAuth:

{
  url: "https://example.com/mcp",
  authProvider: oauthProvider,
}

createConnectorFromConfig

const connector = createConnectorFromConfig({
  command: "node",
  args: ["server.js"],
});

Creates a StdioConnector.

const connector = createConnectorFromConfig({
  url: "http://localhost:3000/mcp",
});

Creates an HttpConnector.

Complete Example

import { MCPClient } from "mcpfy-sdk/client";

const client = new MCPClient({
  mcpServers: {
    calculator: {
      command: "node",
      args: ["calculator-server.js"],
    },
  },
});

try {
  const session = await client.createSession("calculator");

  const tools = await session.listTools();

  console.log("Available tools:");
  for (const tool of tools) {
    console.log(`- ${tool.name}`);
  }

  const result = await session.callTool("add", {
    a: 10,
    b: 20,
  });

  console.log("Tool result:", result);
} finally {
  await client.closeAllSessions();
}

Multiple MCP Servers

const client = new MCPClient({
  mcpServers: {
    calculator: {
      command: "node",
      args: ["calculator-server.js"],
    },

    weather: {
      url: "http://localhost:3000/mcp",
    },

    database: {
      url: "https://example.com/database/mcp",
      authToken: "access-token",
    },
  },
});

const calculator = await client.createSession("calculator");
const weather = await client.createSession("weather");
const database = await client.createSession("database");

Or:

const sessions = await client.createAllSessions();

Error Handling

try {
  const session = await client.createSession("remote");

  const result = await session.callTool("some_tool", {
    value: "example",
  });

  console.log(result);
} catch (error) {
  console.error("MCP operation failed:", error);
}

Public Exports

MCPClient
MCPSession
BaseConnector
StdioConnector
HttpConnector
createConnectorFromConfig

Types:

MCPClientConfig
ServerConfig

Summary

const client = new MCPClient({
  mcpServers: {
    myServer: {
      url: "http://localhost:3000/mcp",
    },
  },
});

const session = await client.createSession("myServer");

const tools = await session.listTools();

const result = await session.callTool("my_tool", {
  value: "example",
});

await client.closeAllSessions();

Use MCPClient for application-level connection management, MCPSession for interacting with a connected server, and connector classes when transport-level control is required.

​MCP Client

​Installation

​Architecture

​Responsibilities

​MCPClient

​Configuration

​Example

​Creating a Session

​Creating All Sessions

​Getting a Session

​Closing Sessions

​Server Configuration

​Stdio Server Example

​Advanced Example

​HTTP Server Example

​Custom Headers

​Bearer Authentication

​OAuth

​MCPSession

​Tools

​List Tools

​Call Tool

​Prompts

​List Prompts

​Get Prompt

​Resources

​List Resources

​Read Resource

​Close Session

​Connectors

​StdioConnector

​HttpConnector

​createConnectorFromConfig

​Complete Example

​Multiple MCP Servers

​Error Handling

​Public Exports

​Summary