Server: PraisonAI MCP

Deploy all PraisonAI capabilities as an MCP server for Claude Desktop, Cursor, Windsurf, and other MCP clients.

Quick Start

Install Dependencies

# Standalone MCP host
pip install "praisonai-mcp[all]"

# Or the full PraisonAI stack
pip install "praisonai[mcp]"

Set API Key

export OPENAI_API_KEY="your-key"

Start MCP Server

praisonai-mcp serve --transport stdio
praisonai mcp serve --transport stdio   # equivalent (umbrella)

praisonai-mcp serve … (standalone) and praisonai mcp serve … (umbrella) are equivalent for host commands. See the praisonai-mcp Package guide and The Three MCP Layers.

Serving Your Own Agents

To publish your agents (not the built-in throwaway assistant), use serve_agents([...]).

from praisonaiagents import Agent
from praisonai_mcp import serve_agents

serve_agents([Agent(name="Support", instructions="Help users.")], port=7777)

See Serve Agents for the full guide.

CLI - STDIO Transport

For Claude Desktop, Cursor, Windsurf local integration:

praisonai-mcp serve --transport stdio
praisonai mcp serve --transport stdio   # equivalent

STDIO transport now works on Windows (ProactorEventLoop + Python 3.13), where it previously crashed with WinError 6. It also survives malformed input and shuts down cleanly. See the STDIO Transport Reliability section.

CLI - HTTP Stream Transport

For remote access (MCP 2025-11-25 spec):

praisonai-mcp serve --transport http-stream --port 8080
praisonai mcp serve --transport http-stream --port 8080

Expected Output:

✓ Starting MCP server 'praisonai' on http://127.0.0.1:8080/mcp

CLI Options

Option	Default	Description
`--transport`	`stdio`	`stdio` or `http-stream`
`--host`	`127.0.0.1`	HTTP host
`--port`	`8080`	HTTP port
`--endpoint`	`/mcp`	HTTP endpoint path
`--api-key`	-	API key for auth
`--name`	`praisonai`	Server name
`--response-mode`	`batch`	`batch` or `stream`
`--cors-origins`	-	Comma-separated CORS origins
`--allowed-origins`	-	Allowed origins for security
`--session-ttl`	`3600`	Session TTL in seconds
`--log-level`	`warning`	`debug`, `info`, `warning`, `error`

Python SDK

from praisonai.mcp_server import MCPServer

server = MCPServer(
    name="praisonai",
    version="1.0.0",
    instructions="PraisonAI MCP Server - AI agent capabilities"
)

# STDIO transport
server.run(transport="stdio")

# Or HTTP Stream transport
server.run(transport="http-stream", host="127.0.0.1", port=8080)

Constants

praisonai_mcp exports two module-level naming constants (in __all__). They back forthcoming session-listing and approval-over-MCP features and keep the vocabulary consistent with the SDK’s list_* verb style.

import praisonai_mcp

praisonai_mcp.SESSION_LIST_TOOL         # "list_sessions"
praisonai_mcp.STATUS_AWAITING_APPROVAL  # "awaiting_approval"

Constant	Value	Meaning
`SESSION_LIST_TOOL`	`"list_sessions"`	Tool name for listing sessions — matches the SDK’s `list_*` verb style.
`STATUS_AWAITING_APPROVAL`	`"awaiting_approval"`	Run status telling you why a run stopped.

MCP Protocol Features

Feature	Supported	Description
Tools	✅	List, call, search tools
Resources	✅	List, read resources
Prompts	✅	List, get prompts
Pagination	✅	Cursor-based pagination
Tool Search	✅	Server-side tool filtering
Progress	✅	Progress notifications
Cancellation	✅	Request cancellation
Logging	✅	Set log level

Protocol Version: 2025-11-25

Generate Client Config

# Claude Desktop
praisonai mcp config-generate --client claude-desktop

# Cursor
praisonai mcp config-generate --client cursor

# VSCode
praisonai mcp config-generate --client vscode

# Windsurf
praisonai mcp config-generate --client windsurf

Since v4.6.154, config-generate auto-detects your install type and emits the matching command (praisonai-mcp for standalone, praisonai for umbrella). Both forms are shown below.

Claude Desktop Output:

Standalone (praisonai-mcp)
Umbrella (praisonai)

{
  "mcpServers": {
    "praisonai": {
      "command": "praisonai-mcp",
      "args": ["serve", "--transport", "stdio"]
    }
  }
}

{
  "mcpServers": {
    "praisonai": {
      "command": "praisonai",
      "args": ["mcp", "serve", "--transport", "stdio"]
    }
  }
}

Connect MCP Client

Claude Desktop (claude_desktop_config.json): For STDIO:

Standalone (praisonai-mcp)
Umbrella (praisonai)

{
  "mcpServers": {
    "praisonai": {
      "command": "praisonai-mcp",
      "args": ["serve", "--transport", "stdio"]
    }
  }
}

{
  "mcpServers": {
    "praisonai": {
      "command": "praisonai",
      "args": ["mcp", "serve", "--transport", "stdio"]
    }
  }
}

For HTTP Stream:

{
  "mcpServers": {
    "praisonai": {
      "url": "http://localhost:8080/mcp",
      "transport": "http-stream"
    }
  }
}

Cursor (.cursor/mcp.json):

Standalone (praisonai-mcp)
Umbrella (praisonai)

{
  "mcpServers": {
    "praisonai": {
      "command": "praisonai-mcp",
      "args": ["serve", "--transport", "stdio"]
    }
  }
}

{
  "mcpServers": {
    "praisonai": {
      "command": "praisonai",
      "args": ["mcp", "serve", "--transport", "stdio"]
    }
  }
}

List Available Tools

praisonai mcp list-tools

Output:

Available MCP Tools (15 of 86):

  • praisonai.memory.show [read-only]
    Show current memory contents

  • praisonai.workflow.run
    Run a workflow from agents.yaml

  • praisonai.agent.chat
    Chat with an agent
...

Agent Tools

The built-in agent tools run a generic, server-owned assistant proxy — not your agents.

Tool	Arguments	Description
`praisonai.agent.chat`	`message`, `model`	Chat one turn with the built-in assistant.
`praisonai.agent.run`	`task`, `model`	Run a one-off task with the built-in assistant.

The instructions= parameter was removed from praisonai.agent.chat and praisonai.agent.run in PR #3531 (fixes #3528). A connecting client can no longer rewrite the assistant’s persona — the server owns it. To publish your agents with your persona, use serve_agents([...]).

Memory Tools

The memory tools call the real core memory API.

Tool	Arguments	Description
`praisonai.memory.show`	`user_id?`	Show stored memory, optionally filtered by `user_id`.
`praisonai.memory.add`	`content`, `metadata?`	Store a short-term memory entry.
`praisonai.memory.search`	`query`, `limit=10`, `user_id?`	Search stored memory.
`praisonai.memory.clear`	—	Clears all memory (short-term + long-term) via `reset_all()`. No per-session clear.

praisonai.memory.sessions was removed in PR #3531 — the tool no longer exists.

Search Tools

# Search by query
praisonai mcp tools search "web"

# Filter by category
praisonai mcp tools search --category memory --read-only

# Get tool info
praisonai mcp tools info praisonai.memory.show

# Get tool schema
praisonai mcp tools schema praisonai.workflow.run

Health Check

praisonai mcp doctor

Output:

PraisonAI MCP Server Health Check

Protocol Version: 2025-11-25
Supported Versions: 2025-11-25, 2025-03-26, 2024-11-05

Registered Components:
  • Tools: 86
  • Resources: 7
  • Prompts: 7

Environment:
  ✓ OPENAI_API_KEY
  ○ ANTHROPIC_API_KEY
  ○ GOOGLE_API_KEY

Dependencies:
  ✓ starlette
  ✓ uvicorn
  ✓ praisonaiagents

✓ MCP server is ready to run

Authentication

For HTTP Stream transport with API key:

praisonai mcp serve --transport http-stream --api-key mykey --port 8080

Client config with auth:

{
  "mcpServers": {
    "praisonai": {
      "url": "http://localhost:8080/mcp",
      "headers": {
        "Authorization": "Bearer mykey"
      }
    }
  }
}

Troubleshooting

Issue	Fix
Missing deps	`pip install "praisonai-mcp[all]"` or `pip install "praisonai[mcp]"`
Port in use	Change `--port`
No tools	Run `praisonai-mcp list-tools`
Auth failed	Check `--api-key`
STDIO not working	Check command path
Config command needs praisonai-code	`pip install praisonai-code` (config commands like `list`/`add`/`sync` require it)
`OSError: [WinError 6] The handle is invalid` on Windows	Upgrade to a `praisonai-mcp` release with the threaded stdin reader — STDIO now works on Windows + Python 3.13
MCP host exits after a client sends binary / non-UTF-8 bytes	Fixed — the server returns a `-32700` parse error and keeps running
`--transport stdio` hangs on shutdown	Fixed — `stop()` unblocks the idle reader for a clean exit

Serve Agents - Publish your own agents as ask_{name} tools
praisonai-mcp Package - Standalone host package guide
The Three MCP Layers - Client vs light server vs heavy host
Tools MCP - Deploy tools as MCP server
Agents MCP - Deploy agents as MCP server
Recipes MCP - Deploy recipes as MCP server

​Quick Start

​Serving Your Own Agents

​CLI - STDIO Transport

​CLI - HTTP Stream Transport

​CLI Options

​Python SDK

​Constants

​MCP Protocol Features

​Generate Client Config

​Connect MCP Client

​List Available Tools

​Agent Tools

​Memory Tools

​Search Tools

​Health Check

​Authentication

​Troubleshooting

​Related

Quick Start

Serving Your Own Agents

CLI - STDIO Transport

CLI - HTTP Stream Transport

CLI Options

Python SDK

Constants

MCP Protocol Features

Generate Client Config

Connect MCP Client

List Available Tools

Agent Tools

Memory Tools

Search Tools

Health Check

Authentication

Troubleshooting

Related