MCP Agent Server

A Model Context Protocol (MCP) hub that seamlessly connects AI clients with intelligent agents, enabling powerful cross-platform communication across multiple AI ecosystems.

Overview

MCP Agent Server creates a bridge between MCP-compatible clients (like Claude Desktop, VS Code, Cursor, etc.) and specialized AI agents. It enables you to:

• Create and configure multiple specialized agents with different capabilities
• Connect these agents to your MCP clients
• Compose agents into master agents for complex workflows
• Build AI applications with advanced capabilities MCP servers

This project leverages the mcp-ai-agent framework to simplify agent creation and management.

Features

• Multiple Agent Support: Create and manage different specialized agents
• Agent Composition: Combine specialized agents into master agents
• Custom Tool Integration: Create your own tools or use existing MCP servers
• Preconfigured Servers: Easy access to popular MCP servers like Sequential Thinking, Brave Search, and Memory
• AI SDK Integration: Support for 17+ LLM providers including OpenAI, Anthropic, Google (Generative AI & Vertex), Amazon Bedrock, Azure, Cohere, Mistral, Fireworks, Groq, Perplexity, Together AI, xAI, DeepSeek, Cerebras, DeepInfra, and Replicate through Vercel AI SDK v5

Prerequisites

• Node.js (v16+) installed
• An API key for your chosen AI model provider (OpenAI, Anthropic, Google, etc.)
• Any API keys required by specific MCP servers you want to use

Installation

Option 1: Using npx (Recommended)

You can run MCP Agent Server directly using npx without installation:

# Start the server with default configuration
npx mcp-agent-server

# Start with custom configuration
npx mcp-agent-server --config my-config.json

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

Option 2: Global Installation

Install globally to use the `mcp-agent-server` command anywhere:

npm install -g mcp-agent-server

# Then use it
mcp-agent-server --config my-config.json

Option 3: Local Development

1. Clone the repository:

git clone 
   cd mcp-agent-server

2. Install dependencies:

npm install

3. Build the project:

npm run build

Configuration

Configure Your Agents

The MCP Agent Server now uses JSON-based configuration for easier management and deployment. You can create a personalized agents configuration file named `my-agents-config.json` in the project root. The server automatically detects and uses this file if it exists.

To create your custom configuration:

1. Create a new file called `my-agents-config.json` in the project root

2. Define your agents with their tools, models, and configurations using JSON format

3. The server will automatically load and use your configuration

JSON Configuration Schema

Here's an example of a custom agents configuration:

{
  "version": "1.0.0",
  "agents": [
    {
      "name": "Code Context Agent",
      "description": "Use this agent to analyze and understand code in your projects",
      "model": {
        "provider": "anthropic",
        "model": "claude-3-5-haiku-20241022"
      },
      "toolsConfigs": [
        {
          "prebuilt": "sequentialThinking"
        },
        {
          "mcpServers": {
            "codeContext": {
              "command": "node",
              "args": ["/path/to/code-context-mcp/dist/index.js"]
            }
          }
        }
      ]
    },
    {
      "name": "Web Search Agent",
      "description": "Use this agent to search the web",
      "systemPrompt": "Prefer to use brave search to search the web for information.",
      "model": {
        "provider": "anthropic",
        "model": "claude-3-5-haiku-20241022"
      },
      "toolsConfigs": [
        {
          "prebuilt": "sequentialThinking"
        },
        {
          "prebuilt": "braveSearch"
        }
      ]
    },
    {
      "name": "Master Agent",
      "description": "An agent that can manage other agents",
      "model": {
        "provider": "openai",
        "model": "gpt-4o-mini"
      },
      "toolsConfigs": [
        {
          "agentRef": "Code Context Agent"
        },
        {
          "agentRef": "Web Search Agent"
        }
      ]
    }
  ]
}

Configuration Options

Model Configuration

• provider: The AI provider to use. Supported providers include:
  • `"openai"` - OpenAI models (GPT-4, GPT-4o, etc.)
  • `"anthropic"` - Anthropic Claude models
  • `"google"` - Google Generative AI (Gemini models)
  • `"vertex"` - Google Vertex AI
  • `"bedrock"` - Amazon Bedrock
  • `"azure"` - Azure OpenAI Service
  • `"cohere"` - Cohere models
  • `"mistral"` - Mistral AI models
  • `"fireworks"` - Fireworks AI
  • `"groq"` - Groq (ultra-fast inference)
  • `"perplexity"` - Perplexity AI
  • `"togetherai"` - Together AI
  • `"xai"` - xAI (Grok models)
  • `"deepseek"` - DeepSeek models
  • `"cerebras"` - Cerebras inference
  • `"deepinfra"` - DeepInfra
  • `"replicate"` - Replicate (open source models)
• model: The specific model name (e.g., `"gpt-4o-mini"`, `"claude-3-5-haiku-20241022"`, `"gemini-2.0-flash-exp"`)
• apiKey: (Optional) API key for the provider. Can also be set via environment variables

Tools Configuration Types

1. Prebuilt Servers (recommended):

{
     "prebuilt": "sequentialThinking"
   }

Available prebuilt servers: `sequentialThinking`, `memory`, `braveSearch`, `firecrawlMcp`, `fetch`, `awsKbRetrieval`, `everart`, `fileSystem`, `sqlite`

2. Custom MCP Servers:

{
     "mcpServers": {
       "serverName": {
         "command": "node",
         "args": ["/path/to/server.js"],
         "env": {
           "API_KEY": "your-api-key"
         }
       }
     }
   }

3. Agent References (for master agents):

{
     "agentRef": "Other Agent Name"
   }

4. Imported Agents (for using external agent files):

{
     "type": "import",
     "importPath": "/path/to/your/agent-file.js",
     "exportName": "createResearchAgent",
     "factoryArgs": {
       "modelProvider": "anthropic",
       "modelName": "claude-3-5-haiku-20241022",
       "includeMemory": true
     }
   }

This allows you to import agents from TypeScript/JavaScript files created with the `mcp-ai-agent` library. The imported file can export:

Selective Agent Exposure

You can control which agents are exposed to MCP clients using the `expose` boolean field on each agent. This is useful when you want to have helper agents that are only used internally by other agents:

{
  "version": "1.0.0",
  "agents": [
    {
      "name": "Web Search Helper",
      "description": "Internal web search capabilities",
      "model": { "provider": "openai", "model": "gpt-4o-mini" },
      "toolsConfigs": [{ "prebuilt": "braveSearch" }],
      "expose": false
    },
    {
      "name": "Master Assistant",
      "description": "Public-facing assistant with web search",
      "model": {
        "provider": "anthropic",
        "model": "claude-3-5-haiku-20241022"
      },
      "toolsConfigs": [
        { "prebuilt": "sequentialThinking" },
        { "agentRef": "Web Search Helper" }
      ],
      "expose": true
    }
  ]
}

• `expose: true` (default): Agent is available as a tool in MCP clients
• `expose: false`: Agent is only available internally to other agents

Specifying Configuration File

You can specify a custom configuration file using the `--config` argument:

# Using CLI
npm run test-agent -- --config="path/to/config.json" --name="Agent Name" --prompt="Test prompt"

# When starting the server (multiple formats supported)
node dist/index.js --config=path/to/config.json
node dist/index.js -c path/to/config.json
node dist/index.js --config path/to/config.json

You can include as many specialized agents as needed, such as:

• Code analysis agents
• Development environment agents
• Knowledge base agents (Obsidian, etc.)
• Project management agents (Jira, etc.)
• Google Drive/Workspace agents
• Web search agents
• Design tool agents (Figma, etc.)

> Important: After creating or updating your custom configuration, remember to:

>

> 1. Run `npm run build` to rebuild the project

> 2. Restart your MCP client to apply changes

Default Configuration

The server comes with a default `agents-config.json` that includes:

1. Sequential Thinking Agent: For complex problem solving

2. Brave Search Agent: For web searching

3. Memory Agent: For storing and retrieving information

4. Master Agent: Combines multiple agents

> Important: After making changes to your agent configurations, remember to:

>

> 1. Run `npm run build` to rebuild the project

> 2. Restart your Claude client to apply changes

> 3. On Windows, you may need to completely close Claude using Task Manager (Ctrl+Alt+Del) as it can continue running in the background

Example Agent Configuration

{
  "version": "1.0.0",
  "agents": [
    {
      "name": "Sequential Thinker",
      "description": "Use this agent to think sequentially and resolve complex problems",
      "model": {
        "provider": "openai",
        "model": "gpt-4o-mini"
      },
      "toolsConfigs": [
        {
          "mcpServers": {
            "sequentialThinking": {
              "command": "npx",
              "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
            }
          }
        }
      ]
    },
    {
      "name": "Claude Assistant",
      "description": "A powerful AI assistant using Claude's capabilities",
      "model": {
        "provider": "anthropic",
        "model": "claude-3-5-sonnet-20241022"
      },
      "toolsConfigs": [
        {
          "mcpServers": {
            "memory": {
              "command": "npx",
              "args": ["-y", "@modelcontextprotocol/server-memory"]
            }
          }
        }
      ]
    },
    {
      "name": "Master Agent",
      "description": "An agent that can manage other agents",
      "model": {
        "provider": "openai",
        "model": "gpt-4o-mini"
      },
      "toolsConfigs": [
        {
          "agentRef": "Sequential Thinker"
        },
        {
          "agentRef": "Memory Agent"
        },
        {
          "agentRef": "Brave Search Agent"
        }
      ]
    }
  ]
}

> Note: The mcp-ai-agent framework supports various AI models through the AI SDK. You can use models from providers such as OpenAI, Anthropic, Google Generative AI, Mistral, Groq, and many others. Check the AI SDK Providers documentation for the complete list of supported models and their capabilities.

Connecting to MCP Clients

Add the MCP Agent Server to your MCP client configuration:

Claude Desktop

Edit your `claude_desktop_config.json`:

Using npx (Recommended)

{
  "mcpServers": {
    "mcp-agent-server": {
      "command": "npx",
      "args": ["mcp-agent-server", "--config", "/path/to/your/config.json"]
    }
  }
}

Using Global Installation

{
  "mcpServers": {
    "mcp-agent-server": {
      "command": "mcp-agent-server",
      "args": ["--config", "/path/to/your/config.json"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key",
        "BRAVE_API_KEY": "your-brave-api-key",
        "ANTHROPIC_API_KEY": "your-anthropic-api-key"
      }
    }
  }
}

Using Local Build

{
  "mcpServers": {
    "mcp-agent-server": {
      "command": "node",
      "args": [
        "/full/path/to/mcp-agent-server/dist/index.js",
        "--config",
        "/path/to/your/config.json"
      ],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key",
        "BRAVE_API_KEY": "your-brave-api-key",
        "ANTHROPIC_API_KEY": "your-anthropic-api-key"
      }
    }
  }
}

> Important: After making changes to `claude_desktop_config.json`, remember to:

>

> 1. Restart your Claude client to apply changes

> 2. On Windows, you may need to completely close Claude using Task Manager (Ctrl+Alt+Del) as it can continue running in the background

VS Code / Cursor / Other MCP Clients

Follow the specific client's instructions for adding MCP servers, using:

• Command: `node`
• Args: `["/full/path/to/mcp-agent-server/dist/index.js"]`

Using Your Agents

Once configured, your agents will appear as tools in your MCP client. For example, in Claude Desktop, you can use them by:

1. Typing `/` to view available tools

2. Selecting one of your configured agents

3. Following the prompts to provide context and a specific task

Advanced Configuration

Custom Tools

For custom functionality, you have several options:

1. Use Prebuilt Servers (recommended): Choose from available prebuilt servers like `sequentialThinking`, `memory`, `braveSearch`, `fetch`, etc.

2. Create Custom MCP Servers: Build your own MCP server and integrate it:

{
  "name": "Calculator Agent",
  "description": "A calculator agent with custom math operations",
  "model": {
    "provider": "openai",
    "model": "gpt-4o-mini"
  },
  "toolsConfigs": [
    {
      "mcpServers": {
        "calculator": {
          "command": "node",
          "args": ["/path/to/your/calculator-mcp-server.js"]
        }
      }
    }
  ]
}

3. Combine Multiple Prebuilt Servers: Mix and match existing servers for complex functionality:

{
  "name": "Multi-Tool Agent",
  "description": "An agent with multiple capabilities",
  "model": {
    "provider": "anthropic",
    "model": "claude-3-5-haiku-20241022"
  },
  "toolsConfigs": [
    {
      "prebuilt": "sequentialThinking"
    },
    {
      "prebuilt": "memory"
    },
    {
      "prebuilt": "fetch"
    }
  ]
}

Importing External Agents

You can import agents from external files. See example: @fkesheh/mcp-ai-agent-example/exportable-agent.ts

1. Create Agent File

// my-agent.ts
import { AIAgent, Servers } from "mcp-ai-agent";
import { openai } from "@ai-sdk/openai";

export const myAgent = new AIAgent({
  name: "My Custom Agent",
  description: "A custom agent",
  model: openai("gpt-4o-mini"),
  toolsConfigs: [Servers.sequentialThinking],
});

2. Build to JavaScript

npx tsc  # Creates my-agent.js in dist/ folder

3. Use in Configuration

{
  "type": "import",
  "importPath": "/full/path/to/dist/my-agent.js",
  "exportName": "myAgent"
}

Important: Always use absolute paths to compiled `.js` files.

Using MCP Servers

The mcp-ai-agent framework supports various MCP servers:

• Sequential Thinking: For breaking down complex problems
• Memory: For persistent storage of information
• Brave Search: For web searches
• And many more...

Troubleshooting

• If agents fail to initialize, check that the MCP servers are correctly configured
• For "npx" commands, ensure the full path is specified if needed
• Verify all required API keys are available in your environment
• Check that the MCP client is correctly configured to use the MCP Agent Server

Development

1. Make changes to the TypeScript files

2. Rebuild with `npm run build`

3. Restart your MCP client to load the changes

CLI Usage

MCP Agent Server comes with a command-line interface (CLI) for working with agents.

Testing Agents

You can test individual agents directly from the command line without connecting to an MCP client, this is helpful for debugging purposes.

Using npx (Recommended)

npx mcp-agent-server test-agent --config="/path/to/config.json" --name="Agent Name" --prompt="Your test prompt" --context="Optional context"

For example, to test the Brave Search Agent:

npx mcp-agent-server test-agent --config="./agents-config.json" --name="Brave Search" --prompt="What is the capital of France?" --context="I need geographical information"

Or test the Master Agent which combines multiple specialized agents:

npx mcp-agent-server test-agent --config="./my-agents-config.json" --name="Master Agent" --prompt="Store this information: Claude is an AI assistant by Anthropic" --context="I need to test the memory capabilities"

> Note: If no `--config` is specified, the server will look for `agents-config.json` or `my-agents-config.json` in the current directory.

Using Local Development

npm run test-agent -- --config="path/to/config.json" --name="Agent Name" --prompt="Your test prompt" --context="Optional context"

Or run the command directly:

node dist/cli.js test-agent --config="./agents-config.json" --name="Sequential Thinker" --prompt="How would I approach solving a complex math problem?"

The test command will:

1. Find the specified agent by name

2. Initialize the agent

3. Send your prompt and context

4. Display the agent's response

This is useful for:

• Testing new agent configurations
• Debugging agent issues
• Verifying agent functionality before connecting to an MCP client

The test command will list all available agents if you provide an invalid agent name.

License

This project is licensed under the MIT License.