Skip to main content
The MCPClient is your gateway to connecting with MCP servers. This guide covers all configuration options for establishing connections, managing sessions, and customizing client behavior.
Looking for agent configuration? If you’re building AI agents that interact with MCP servers, see the Agent Configuration guide instead.

​
Quick Start

import { MCPClient } from 'mcp-use'

// Configure your MCP servers
const config = {
    mcpServers: {
        playwright: {
            command: 'npx',
            args: ['@playwright/mcp@latest'],
            env: { DISPLAY: ':1' }
        }
    }
}

const client = new MCPClient(config)

​
Server Configuration

The MCPClient uses a flexible configuration system that supports any MCP server, regardless of connection type.
Looking for MCP servers? Check out these curated lists:

​
Configuration Structure

Server configuration is defined as a JavaScript object: 
{
  "mcpServers": {
    "server_name": {
      "command": "command_to_run",
      "args": ["arg1", "arg2"],
      "env": {
        "ENV_VAR": "value"
      }
    }
  }
}

​
Configuration Parameters

Each server entry requires a unique name and connection-specific parameters. The client automatically detects the connection type based on the provided configuration. Common Parameters:
  • server_name: Unique identifier for the server (used as the object key)
STDIO Servers (Local Process): For servers that run as local child processes:
  • command: Executable command to start the server (e.g., "npx", "python")
  • args: Array of command-line arguments
  • env: Environment variables for the server process
HTTP/HTTPS Servers (Remote): For servers accessible via HTTP endpoints:
  • url: Full URL to the MCP server endpoint
  • headers: Custom HTTP headers (useful for authentication)
The client automatically infers the connection type based on your configuration. Use command for STDIO servers or url for HTTP servers. See Connection Types for detailed information.

​
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/pietro/projects/mcp-use/"
      ]
    }
  }
}
For a complete example of using multiple servers, see the multi-server example in our repository.

​
Client Creation Methods

There are several ways to create an MCPClient:

​
From Dictionary/Object

Create configuration programmatically:
TypeScript
import { MCPClient } from 'mcp-use'

const config = {
    mcpServers: {
        playwright: {
            command: 'npx',
            args: ['@playwright/mcp@latest'],
            env: { DISPLAY: ':1' }
        }
    }
}

const client = new MCPClient(config)

​
From Configuration File

Load configuration from a JSON file: 
import { MCPClient, loadConfigFile } from 'mcp-use'

const config = await loadConfigFile('config.json')
const client = new MCPClient(config)

​
With Sandbox Options

Enable sandboxed execution: 
// Note: Sandbox mode is not yet supported in the TypeScript library
// This is a planned feature for a future release

​
Best Practices

  1. API Keys: Always use environment variables for sensitive information
  2. Configuration Files: Keep configuration files in version control (without sensitive data)
  3. Server Naming: Use descriptive names for your MCP servers
  4. Environment Variables: Set appropriate environment variables for each server
  5. Testing: Test server connections independently before using with agents
  6. Monitoring: Enable logging to monitor server connection health

​
Error Handling

Common client configuration errors and solutions:
  1. Server Not Found: Check if the server command is installed and accessible
  2. Connection Timeout: Verify server is running and network connectivity
  3. Permission Denied: Ensure proper file permissions and environment setup
  4. Invalid Configuration: Validate JSON syntax and required fields
For detailed information, see the Connection Types guide.