​

API Reference

​

MCPClient

​

Initialization Methods

​

From Config File

import { MCPClient } from 'easy-mcp-use';

const client = MCPClient.fromConfigFile("config.json");

​

From Dictionary

import { MCPClient, MCPConfig } from 'easy-mcp-use';

const config: MCPConfig = {
  mcpServers: {
    my_server: {
      command: "npx",
      args: ["@my-mcp/server"],
      env: {
        PORT: "3000"
      }
    }
  }
};

const client = MCPClient.fromDict(config);

​

Core Methods

​

createSession

const session = await client.createSession({
  serverName: "my_server",
  timeout: 30.0,
  retryCount: 3
});

• Use a longer timeout for servers that take more time to initialize
• Increase retryCount in unstable network environments
• Use specific serverName when working with multiple servers in the same config

​

closeSession

await client.closeSession(sessionId);

​

closeAllSessions

await client.closeAllSessions();

• Always call this at the end of your application to clean up resources
• Use when switching between different tasks that require different servers

​

getServer

const server = client.getServer("my_server");

​

MCPAgent

​

Initialization

import { MCPAgent, MCPClient } from 'easy-mcp-use';
import { ChatOpenAI } from 'langchain/chat_models/openai';

const agent = new MCPAgent({
  llm: new ChatOpenAI({ modelName: "gpt-4", temperature: 0.7 }),
  client: MCPClient.fromConfigFile("config.json"),
  maxSteps: 30,
  sessionOptions: { timeout: 60.0 },
  autoInitialize: true,
  memoryEnabled: true,
  systemPrompt: null,
  systemPromptTemplate: null,
  additionalInstructions: null,
  disallowedTools: null,
  useServerManager: false
});

• llm:
  • easy-mcp-use supports ANY LLM that is compatible with LangChain
  • You can use models from OpenAI, Anthropic, Google, Mistral, Groq, Cohere, or any other provider with a LangChain integration
  • You can even use open source models via LlamaCpp, HuggingFace, or other interfaces
  • Custom or self-hosted models are also supported as long as they implement LangChain’s interface
• maxSteps:
  • Increase for complex tasks that require many interactions
  • Decrease for simpler tasks to improve efficiency
  • Use higher values (50+) for web browsing or multi-stage tasks
  • Use lower values (10-20) for targeted, specific tasks
• systemPrompt / systemPromptTemplate:
  • Use to customize the initial instructions given to the LLM
  • Helps shape the agent’s behavior and capabilities
  • Use for specialized tasks or custom interaction patterns
• memoryEnabled:
  • Enable to maintain conversation history
  • Disable for stateless operation or to save on token usage
• sessionOptions:
  • Customize timeout for long-running server operations
  • Set retry parameters for unstable connections
• useServerManager:
  • Set to true when using an MCPClient configured with multiple servers to enable efficient, automatic server selection per tool call. This can reduce agent confusion and minimize unnecessary server connections.
  • Keep as false (default) if using a single server or if you prefer to manually specify the target server using the serverName parameter in agent.run() or rely on the agent to handle tool availability across all connected servers.
• disallowedTools:
  • Use to restrict which tools the agent can access
  • Helpful for security or to limit agent capabilities
  • Useful when certain tools might be dangerous or unnecessary for a specific task
  • Can be updated after initialization using setDisallowedTools()

​

Core Methods

​

run

const result = await agent.run({
  query: "Find information about TypeScript libraries",
  maxSteps: 25,
  stopOnFirstResult: false,
  serverName: "my_server",
  callbacks: []
});

• maxSteps: Override the instance default for specific queries
• stopOnFirstResult: Use true for simple lookups, false for thorough exploration
• serverName: Specify when using multiple servers for different tasks
• callbacks: Add for monitoring or logging specific runs

​

reset

agent.reset();

• Between different tasks to clear context
• When starting a new conversation thread
• When agent gets stuck in a particular strategy

​

getHistory

const history = agent.getHistory();

• For debugging agent behavior
• When implementing custom logging
• To provide context for follow-up queries

​

setDisallowedTools

agent.setDisallowedTools(["tool1", "tool2"]);

• To restrict access to specific tools for security reasons
• To limit agent capabilities for specific tasks
• To prevent the agent from using potentially dangerous tools
• Note: Changes take effect on next initialization

​

getDisallowedTools

const disallowed = agent.getDisallowedTools();

• To check which tools are currently restricted
• For debugging or auditing purposes
• To verify tool restrictions before running the agent

​

Configuration Details

​

MCP Server Configuration Schema

{
  "mcpServers": {
    "server_name": {
      "command": "command_to_run",
      "args": ["arg1", "arg2"],
      "env": {
        "ENV_VAR": "value"
      },
      "timeout": 30.0,
      "retry": {
        "maxAttempts": 3,
        "backoffFactor": 1.5
      }
    }
  }
}

• command & args: Vary based on the specific MCP server implementation
• env:
  • Set environment-specific variables needed by the server
  • Override default server settings (ports, directories)
  • Set display settings for GUI-based servers
• timeout:
  • Increase for servers with longer startup times
  • Lower for simpler servers to fail fast
• retry configuration:
  • Adjust for different network conditions
  • Increase maxAttempts in unstable environments
  • Adjust backoffFactor based on server behavior

​

Error Handling

import { MCPConnectionError, MCPTimeoutError } from 'easy-mcp-use';

try {
  const result = await agent.run({ query: "Find information" });
} catch (error) {
  if (error instanceof MCPConnectionError) {
    // Handle connection issues
    console.log("Failed to connect to the MCP server");
  } else if (error instanceof MCPTimeoutError) {
    // Handle timeout issues
    console.log("Operation timed out");
  } else {
    // Handle other exceptions
    console.log(`An error occurred: ${error}`);
  }
}

​

Advanced Usage

​

Multi-Server Configuration

import { MCPClient, MCPAgent, MCPConfig } from 'easy-mcp-use';
import { ChatOpenAI } from 'langchain/chat_models/openai';

// Create client with multiple servers
const config: MCPConfig = {
  mcpServers: {
    browser: {
      command: "npx",
      args: ["@playwright/mcp@latest"]
    },
    custom_server: {
      command: "node",
      args: ["-r", "ts-node/register", "my_custom_mcp_server.ts"]
    }
  }
};

const client = MCPClient.fromDict(config);

// Create agent
const agent = new MCPAgent({
  llm: new ChatOpenAI({ modelName: "gpt-4" }),
  client: client
});

// Run with specific server
const resultBrowser = await agent.run({
  query: "Search the web for TypeScript libraries",
  serverName: "browser"
});

// Run with different server
const resultCustom = await agent.run({
  query: "Perform custom operation",
  serverName: "custom_server"
});

​

Custom Output Parsing

import { OutputParser } from 'langchain/schema';
import { MCPAgent, MCPClient } from 'easy-mcp-use';

class CustomOutputParser implements OutputParser {
  parse(text: string): any {
    // Custom parsing logic
    return processedResult;
  }
}

// Use the custom parser
const agent = new MCPAgent({
  llm: llm,
  client: client,
  outputParser: new CustomOutputParser()
});

• The MCP server returns structured data that needs special handling
• You need to extract specific information from responses
• You’re integrating with custom or specialized MCP servers

​

Restricting Tool Access

import { MCPAgent, MCPClient } from 'easy-mcp-use';
import { ChatOpenAI } from 'langchain/chat_models/openai';

// Create agent with restricted tools
const agent = new MCPAgent({
  llm: new ChatOpenAI({ modelName: "gpt-4" }),
  client: client,
  disallowedTools: ["file_system", "network", "shell"]  // Restrict potentially dangerous tools
});

// Update restrictions after initialization
agent.setDisallowedTools(["file_system", "network", "shell", "database"]);
await agent.initialize();  // Reinitialize to apply changes

// Check current restrictions
const restrictedTools = agent.getDisallowedTools();
console.log(`Restricted tools: ${restrictedTools}`);

• You need to restrict access to sensitive operations
• You want to limit the agent’s capabilities for specific tasks
• You’re concerned about security implications of certain tools
• You want to focus the agent on specific functionality