​

Configuration Guide

This guide covers all the configuration options available in easy-mcp-use.

​

API Keys

Make sure to have the API key relative to the provider of your choice available in the environment. You can either:

1 - Create .env file with your keys as:

# OpenAI
OPENAI_API_KEY=your_api_key_here
# Anthropic
ANTHROPIC_API_KEY=your_api_key_here
# Groq
GROQ_API_KEY=your_api_key_here

and load it in your TypeScript code using:

import dotenv from 'dotenv';
dotenv.config();

This will make all the keys defined in .env available in your runtime, granted that you run from where the .env is located.

2 - Set it in your environment by running in your terminal the following command, e.g. for OpenAI:

export OPENAI_API_KEY='...'

and then import it in your TypeScript code as:

const OPENAI_API_KEY = process.env.OPENAI_API_KEY || '';

or any other method you might prefer.

​

MCP Server Configuration

easy-mcp-use supports any MCP server through a flexible configuration system. (For a list of awesome servers you can visit https://github.com/punkpeye/awesome-mcp-servers or https://github.com/appcypher/awesome-mcp-servers which have an amazing collection of them)

The configuration is defined in a JSON file with the following structure:

{
  "mcpServers": {
    "server_name": {
      "command": "command_to_run",
      "args": ["arg1", "arg2"],
      "env": {
        "ENV_VAR": "value"
      }
    }
  }
}

MCP servers can use different connection types (STDIO, HTTP). For details on these connection types and how to configure them, see the Connection Types guide.

​

Configuration Options

• server_name: A unique identifier for your MCP server
• command: The command to start the MCP server
• args: Array of arguments to pass to the command
• env: Environment variables to set for the server

​

Example Configuration

Here’s a basic example of how to configure an MCP server:

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

​

Multiple Server Configuration

You can configure multiple MCP servers in a single configuration file, allowing you to use different servers for different tasks or combine their capabilities (e.g.):

{
  "mcpServers": {
    "airbnb": {
      "command": "npx",
      "args": ["-y", "@openbnb/mcp-server-airbnb", "--ignore-robots-txt"]
    },
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"],
      "env": { "DISPLAY": ":1" }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects/easy-mcp-use/"]
    }
  }
}

For a complete example of using multiple servers, see the multi-server example in our repository.

​

Agent Configuration

When creating an MCPAgent, you can configure several parameters:

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

// Basic configuration
const agent = new MCPAgent({
  llm: new ChatOpenAI({ modelName: "gpt-4", temperature: 0.7 }),
  client: MCPClient.fromConfigFile("config.json"),
  maxSteps: 30
});

// Advanced configuration
const agent = new MCPAgent({
  llm: new ChatOpenAI({ modelName: "gpt-4", temperature: 0.7 }),
  client: MCPClient.fromConfigFile("config.json"),
  maxSteps: 30,
  serverName: undefined,
  autoInitialize: true,
  memoryEnabled: true,
  systemPrompt: "Custom instructions for the agent",
  additionalInstructions: "Additional guidelines for specific tasks",
  disallowedTools: ["file_system", "network", "shell"]  // Restrict potentially dangerous tools
});

​

Available Parameters

• llm: Any LangChain-compatible language model (required)
• client: The MCPClient instance (optional if connectors are provided)
• connectors: List of connectors if not using client (optional)
• serverName: Name of the server to use (optional)
• maxSteps: Maximum number of steps the agent can take (default: 5)
• autoInitialize: Whether to initialize automatically (default: false)
• memoryEnabled: Whether to enable memory (default: true)
• systemPrompt: Custom system prompt (optional)
• systemPromptTemplate: Custom system prompt template (optional)
• additionalInstructions: Additional instructions for the agent (optional)
• disallowedTools: List of tool names that should not be available to the agent (optional)

​

Tool Access Control

You can restrict which tools are available to the agent for security or to limit its capabilities:

// 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}`);

This feature is useful for:

• Restricting access to sensitive operations
• Limiting agent capabilities for specific tasks
• Preventing the agent from using potentially dangerous tools
• Focusing the agent on specific functionality

​

Error Handling

easy-mcp-use provides several ways to handle errors:

1. Connection Errors: Check your MCP server configuration and ensure the server is running
2. Authentication Errors: Verify your API keys are correctly set in the environment
3. Timeout Errors: Adjust the maxSteps parameter if operations are timing out