mcp-agent

MCP Agent Server acts as a bridge between MCP clients and specialized AI agents. It enables you to create multiple dedicated agents with their own tools and models, and even compose them into master agents to handle complex workflows. The server integrates with the mcp-ai-agent framework, giving you a scalable way to expose agent capabilities to MCP clients such as Claude Desktop, VS Code, and Cursor. You can run predefined prebuilt servers or connect your own custom MCP servers as tools for these agents, allowing flexible toolchains and retrieval components within your agent networks.

Prerequisites:

• Node.js v16+ installed
• npm or pnpm available
• An API key for your chosen AI provider (OpenAI, Anthropic, Google, etc.)
• Optional: API keys for any additional MCP servers you plan to use

Installation options:

Option 1: Use npx (recommended)

1. Start the server with default configuration:

npx mcp-agent-server

2. Start with a custom configuration file (if you have my-agents-config.json in the project root):

npx mcp-agent-server --config my-agents-config.json

3. Test an agent (example):

npx mcp-agent-server test-agent --name "Sequential Thinker" --prompt "What is 2+2?"

Option 2: Global installation

npm install -g mcp-agent-server

# Then run
mcp-agent-server --config my-agents-config.json

Option 3: Local development

git clone <repository-url>
cd mcp-agent-server
npm install
npm run build

4. Verify the server starts and is reachable via MCP clients.

You can supply a custom configuration file to define agents, models, and tools using the JSON schema described in the README. Ensure your environment has any required API keys or endpoint configurations for your chosen providers and MCP servers.

Notes and tips:

• The server supports both prebuilt tool servers (e.g., sequentialThinking, braveSearch, memory) and custom MCP servers defined under the mcpServers section of your agent config.
• You can expose or hide agents from MCP clients by using the expose flag in your agent definitions. Default is expose: true.
• When adding custom MCP servers, you can pass environment variables via the env object inside a server definition.
• Use the --config flag to point to a JSON configuration file that defines agents, models, and tools. The server will load this configuration on startup if present.
• Ensure your API keys and provider configurations are secured; avoid hard-coding sensitive keys in public repos and consider using environment variables or secret management.
• For debugging, look for logs emitted by the MCP Agent Server during boot and agent execution; common issues include misconfigured provider models, missing tool endpoints, and network access problems.