Server: PraisonAI MCP

Deploy full PraisonAI capabilities as MCP server using praisonai mcp serve

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

Quick Start

1. Install Dependencies

   # Standalone MCP host
   pip install "praisonai-mcp[all]"
   
   # Or the full PraisonAI stack
   pip install "praisonai[mcp]"
   
2. Set API Key

   export OPENAI_API_KEY="your-key"
   
3. 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.

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)

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)

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

Umbrella (praisonai)

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

Connect MCP Client

Claude Desktop (claude_desktop_config.json):

For STDIO:

Standalone (praisonai-mcp)

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

Umbrella (praisonai)

{
  "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)

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

Umbrella (praisonai)

{
  "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
...

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

Related

• 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