mcp-agent

mcp-agent provides a TypeScript framework to build AI agents that can interact with MCP-enabled services and tools. Agents can be configured with a combination of LLM drivers, local function tools, and MCP server tools, allowing them to perform tasks through orchestrated workflows such as the Orchestrator pattern. The library emphasizes type safety and modular tool provisioning, with a Connection Manager handling shared MCP server connections and per-agent Aggregators that expose only the tools each agent should access. You can integrate with a frontend, a backend service, or run standalone scripts that demonstrate agent collaboration and tool usage. Typical use cases include building agents that search local or remote data, invoke external MCP servers for file or web operations, and chain actions across multiple steps in an automated workflow.

Prerequisites:

• Node.js 18+ (or the version recommended by the project)
• npm or pnpm

Install the MCP agent package:

npm install @joshuacalpuerto/mcp-agent

If you are starting from a fresh repository, you can also install via npm in a project that uses TypeScript:

npm install --save-dev typescript @types/node

Set up a basic build/run workflow (example):

# Initialize a simple TS project (if needed)
npx tsc --init

# Create a minimal script that imports the library and runs a demo

Configure environment variables as needed for your MCP servers and LLM providers (e.g., EXA_API_KEY, FIREWORKS_API_KEY).

Run a quick stand-alone demo as described in the repository's Quick Start section:

node --loader ts-node/esm ./demo/standalone/index.ts

Notes:

• The MCP architecture relies on a global Connection Manager and per-agent Aggregators to optimize resource usage and isolation. If you run multiple agents, expect shared MCP server connections rather than duplicating servers.
• When configuring MCP servers, specify the transport type supported by your environment (stdio, sse, streamable-http, websockets).
• Ensure your LLM provider credentials are securely managed (e.g., via environment variables or secrets management in your deployment pipeline).
• If you extend tools with local functions, keep type signatures strict to leverage TypeScript safety.
• For debugging, enable verbose logs in your LLM and MCP server configurations to trace tool invocations and responses.