praisonai-mcp is the standalone package that hosts your PraisonAI agents and tools as an MCP server — reachable from Claude Desktop, Cursor, Windsurf, and any other MCP client, usable on its own or inside the full praisonai stack.
praisonai-mcp serve and this agent becomes a tool your MCP client can call.
Quick Start
1
Install the package
2
Set your API key
3
Serve over STDIO
Install
Pick the extras you need — core alone covers the CLI and STDIO transport.pip install "praisonai[mcp]" installs praisonai-mcp for you as part of the umbrella product.Three MCP Layers
Three different packages serve three different MCP roles — don’t conflate them.
See The Three MCP Layers for a decision diagram.
CLI Reference
The package ships apraisonai-mcp console script. Inside the full stack the same commands are available as praisonai mcp ….
Host commands
These work withpraisonai-mcp alone — no other package required.
The host also registers four memory tools — see MCP Memory Tools — and four todo tools — see MCP Todo Tools.
Config commands
These read and write the shared PraisonAI configuration, which lives inpraisonai-code. Install it to enable them.
Install Matrix
Which entrypoints exist depends on what you install.Graceful Install Hint
Run a config command with onlypraisonai-mcp installed and you get an actionable hint instead of a traceback.
serve, list-tools, doctor, serve-recipe) never need praisonai-code.
Backward Compatibility
Everything from the pre-extraction layout keeps working.praisonai.mcp_server is a compatibility shim that re-exports praisonai_mcp.mcp_server, so existing scripts need no changes.Best Practices
Install only the extras you use
Install only the extras you use
Core covers the CLI and STDIO transport. Add
[server] for HTTP-stream and [auth] for OAuth 2.1 / OIDC. [all] bundles both.Co-install praisonai-code for config management
Co-install praisonai-code for config management
Host commands run standalone, but
list, add, sync, and friends read the shared config that ships with praisonai-code.Use the standalone CLI in slim environments
Use the standalone CLI in slim environments
praisonai-mcp runs without the full wrapper, keeping MCP-host images small.Run doctor before your first serve
Run doctor before your first serve
praisonai-mcp doctor checks protocol version, registered components, API keys, and dependencies in one pass. Add --json in CI or pre-flight deploy scripts — it emits parseable output ({"error": "...", "ready": false} on failure) and never trips on Windows cp1252 consoles.STDIO transport reliability
STDIO transport reliability
The STDIO transport is hardened for real MCP clients. It runs on Windows + Python 3.13 (previously blocked by
WinError 6) by reading stdin on a dedicated thread, turns malformed input into a JSON-RPC -32700 parse error instead of crashing, bounds the input queue to 1000 lines with backpressure, and shuts down cleanly on Ctrl+C or client disconnect. See MCP STDIO Server Transport.Related
PraisonAI MCP Server
Heavy MCP host reference and client setup.
The Three MCP Layers
Client vs light server vs heavy host, with a decision diagram.
Package Tiers
How the seven packages stack.
MCP Integration
Connect agents to external MCP servers.
MCP Memory Tools
Four memory tools this host exposes to any MCP client.
MCP Todo Tools
Four todo tools sharing the runtime’s store.