npcpy

npcpy is a flexible agent framework for building AI applications and conducting research with LLMs. Its MCP (Model Context Protocol) server enables coordinated multi-agent workflows, tool calling, and orchestration across agents and teams. With the server running, NPCs and teams can be connected to the MCP server to expose their tools and workflows to other agents, enabling complex, collaborative tasks such as data analysis, code review, file operations, and dynamic tool invocation. The server acts as a bridge between NPC-driven agents and external tools, enabling managed runtimes and consistent communication patterns for tool usage and result aggregation.

To use the MCP server, start the server process (see installation steps) and connect clients (NPCs) to it. Once connected, agents can call tools exposed by other agents or by the server itself, trigger multi-agent orchestration (e.g., a coordinator delegating tasks to a data analyst and a writer), and retrieve structured results including tool outputs and synthesized final responses. The server supports streaming responses, JSON-formatted outputs, and the ability to pass contextual information such as team context, models, and providers to guide agent behavior during tool calls.

Prerequisites

• Python 3.8+ installed on your system
• Access to a terminal/command prompt
• Internet connection to install dependencies

1. Create a virtual environment (recommended)

• macOS/Linux: python3 -m venv venv source venv/bin/activate
• Windows: python -m venv venv .\venv\Scripts\activate

2. Install the npcpy package (or install from source if developing)

pip install npcpy

3. Verify installation

python -c "import npcpy; print(npcpy.__version__)"

4. Start the MCP server

# From project root, using module-based execution as defined in mcp_config
python -m npcpy.mcp_server

5. Connect clients to the MCP server (NPCs/teams) following the client documentation for npcpy.

Prerequisites recap

• Ensure Python is installed and accessible in your PATH
• Install npcpy and any optional providers/tools you plan to use
• Ensure network access if running server remotely or behind a firewall

Tips and common issues:

• If the MCP server fails to start due to port conflicts, specify a different port in the server startup configuration or via environment variables if supported by your setup.
• When connecting NPCs or teams, ensure the client is configured with the correct server address and authentication if required.
• Tools exposed via MCP should be well-scoped in their input/output formats; use consistent schemas for tool results to simplify downstream processing.
• For streaming responses, ensure the client is capable of handling incremental chunks and rendering or aggregating results as they arrive.
• If you run into import errors, verify that the Python environment where the server runs has npcpy and its dependencies installed (activate the correct virtual environment).
• Environment variables can be used to configure model/provider defaults, API keys, or logging levels; consult your deployment guide for recommended variables.