praisonai-mcp Package

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.

from praisonaiagents import Agent

agent = Agent(name="assistant", instructions="Answer questions and run tasks.")
agent.start("Summarise today's release notes.")

Run praisonai-mcp serve and this agent becomes a tool your MCP client can call.

Quick Start

Install the package

pip install praisonai-mcp

Set your API key

export OPENAI_API_KEY=sk-...

Serve over STDIO

praisonai-mcp serve --transport stdio

Point Claude Desktop or Cursor at this command and your agents appear as MCP tools.

Install

Pick the extras you need — core alone covers the CLI and STDIO transport.

pip install praisonai-mcp              # core CLI + STDIO
pip install "praisonai-mcp[server]"    # HTTP-stream transport
pip install "praisonai-mcp[auth]"      # OAuth 2.1 / OIDC auth
pip install "praisonai-mcp[all]"       # everything

Command	Extras	Adds	Use it for
`pip install praisonai-mcp`	(none)	`praisonaiagents>=1.6.126`, `mcp>=1.20.0`, `rich`, `typer`, `click`	Core CLI + STDIO transport
`pip install "praisonai-mcp[server]"`	`server`	`starlette>=0.36.0`, `uvicorn>=0.27.0`	HTTP-stream transport
`pip install "praisonai-mcp[auth]"`	`auth`	`httpx>=0.27.0`	OAuth 2.1 / OIDC auth
`pip install "praisonai-mcp[all]"`	`all`	server + auth	Everything
`pip install "praisonai[mcp]"`	via wrapper	full stack	Umbrella install

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.

Layer	Package	Role
Client	`praisonaiagents[mcp]`	Connect agents to external MCP servers
Light server	`praisonai-code` (`praisonai serve mcp`)	Basic `ToolsMCPServer`
Heavy host	`praisonai-mcp` (this package)	Full capability / recipe MCP server

See The Three MCP Layers for a decision diagram.

CLI Reference

The package ships a praisonai-mcp console script. Inside the full stack the same commands are available as praisonai mcp ….

Host commands

These work with praisonai-mcp alone — no other package required.

praisonai-mcp serve --transport stdio      # start the MCP host
praisonai-mcp list-tools                    # list exposed tools
praisonai-mcp doctor                        # health check
praisonai-mcp serve-recipe support-reply    # serve a recipe as MCP

Command	What it does
`serve`	Start the MCP server host (STDIO or HTTP-stream)
`list-tools`	List tools exposed by the host
`doctor`	Check host health, dependencies, and environment
`serve-recipe`	Serve a recipe as an MCP server

Config commands

These read and write the shared PraisonAI configuration, which lives in praisonai-code. Install it to enable them.

praisonai-mcp list                # list configured MCP servers
praisonai-mcp add fs "npx …"      # add a server
praisonai-mcp remove fs           # remove a server
praisonai-mcp test fs             # test a connection
praisonai-mcp sync                # index tool schemas
praisonai-mcp tools               # list indexed tools
praisonai-mcp describe fs read    # show a tool schema
praisonai-mcp status              # server status
praisonai-mcp run fs              # run a configured server
praisonai-mcp auth github         # OAuth login
praisonai-mcp logout github       # clear credentials

Install Matrix

Which entrypoints exist depends on what you install.

Install	`praisonai mcp`	`praisonai serve mcp`	`praisonai-mcp` script
`pip install praisonai-mcp`	—	—	✅
`pip install praisonai-code` only	hidden	✅ (light)	—
`pip install "praisonai[mcp]"`	✅	✅	✅
`pip install praisonai`	✅	✅	✅

Graceful Install Hint

Run a config command with only praisonai-mcp installed and you get an actionable hint instead of a traceback.

praisonai-mcp list

MCP configuration commands require praisonai-code.
Install it with: pip install praisonai-code
(or install the full stack: pip install "praisonai[mcp]")

Host commands (serve, list-tools, doctor, serve-recipe) never need praisonai-code.

Backward Compatibility

Everything from the pre-extraction layout keeps working.

Old usage	Still works	Canonical form
`from praisonai.mcp_server.server import MCPServer`	✅	`from praisonai_mcp.mcp_server.server import MCPServer`
`from praisonai.cli.commands.mcp import app`	✅	`from praisonai_mcp.cli.commands.mcp import app`
`praisonai mcp serve …`	✅	`praisonai-mcp serve …`

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

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

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

praisonai-mcp runs without the full wrapper, keeping MCP-host images small.

Run doctor before your first serve

praisonai-mcp doctor checks protocol version, registered components, API keys, and dependencies in one pass.

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.

Load MCP Tools

The Three MCP Layers

​Quick Start

​Install

​Three MCP Layers

​CLI Reference

​Host commands

​Config commands

​Install Matrix

​Graceful Install Hint

​Backward Compatibility

​Best Practices

​Related

PraisonAI MCP Server

The Three MCP Layers

Package Tiers

MCP Integration

Quick Start

Install

Three MCP Layers

CLI Reference

Host commands

Config commands

Install Matrix

Graceful Install Hint

Backward Compatibility

Best Practices

Related