PraisonAI MCP Server

Run PraisonAI as an MCP server for Claude Desktop, Cursor, and other MCP clients

PraisonAI MCP Server

PraisonAI can expose its capabilities via the Model Context Protocol (MCP), allowing integration with Claude Desktop, Cursor, Windsurf, VSCode, and other MCP-compatible clients.

Protocol Version

PraisonAI MCP Server implements MCP Protocol Version 2025-11-25.

Quick Start

STDIO Transport (Recommended for Claude Desktop)

praisonai mcp serve --transport stdio

HTTP Stream Transport

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

Features

• 70+ MCP Tools - Access all PraisonAI capabilities as MCP tools
• 7 MCP Resources - Read-only access to configuration and status
• 7 MCP Prompts - Pre-built prompts for common tasks
• STDIO Transport - For Claude Desktop and local integrations
• HTTP Stream Transport - For web-based integrations
• Session Management - Full session support with resumability
• Origin Validation - Security for HTTP transport
• Progress Notifications - For long-running operations

Installation

pip install praisonai[mcp]

CLI Commands

Start Server

# STDIO transport (for Claude Desktop)
praisonai mcp serve --transport stdio

# HTTP Stream transport
praisonai mcp serve --transport http-stream --port 8080

# With authentication
praisonai mcp serve --transport http-stream --api-key YOUR_KEY

# With custom allowed origins
praisonai mcp serve --transport http-stream --allowed-origins "http://localhost:3000"

List Components

# List available tools
praisonai mcp list-tools

# List available resources
praisonai mcp list-resources

# List available prompts
praisonai mcp list-prompts

Generate Client Config

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

# For Cursor
praisonai mcp config-generate --client cursor

# For VSCode
praisonai mcp config-generate --client vscode

# For Windsurf
praisonai mcp config-generate --client windsurf

Health Check

praisonai mcp doctor

Server Options

Option	Description	Default
--transport	Transport type: stdio or http-stream	stdio
--host	HTTP host	127.0.0.1
--port	HTTP port	8080
--endpoint	HTTP endpoint path	/mcp
--api-key	API key for authentication	None
--name	Server name	praisonai
--response-mode	Response mode: batch or stream	batch
--cors-origins	Comma-separated CORS origins	*
--allowed-origins	Comma-separated allowed origins	localhost
--session-ttl	Session TTL in seconds	3600
--no-termination	Disable client session termination	False
--resumability	Enable SSE resumability	True
--log-level	Log level: debug, info, warning, error	warning

Client Configuration

Claude Desktop

Add to ~/.config/claude/claude_desktop_config.json (macOS/Linux) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

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

Cursor

Add to Cursor MCP settings:

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

HTTP Stream Client

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

Environment Variables

Set these for full functionality:

export OPENAI_API_KEY=your_key
export ANTHROPIC_API_KEY=your_key  # Optional
export GOOGLE_API_KEY=your_key     # Optional

Available Tools

Run praisonai mcp list-tools to see all available tools. Key categories:

Agent Tools

• praisonai.agent.chat - Chat with an agent
• praisonai.agent.run - Run a task with an agent
• praisonai.workflow.run - Run a workflow
• praisonai.research.run - Run deep research

Capability Tools

• praisonai.chat.completion - Chat completion
• praisonai.images.generate - Generate images
• praisonai.audio.transcribe - Transcribe audio
• praisonai.audio.speech - Text to speech
• praisonai.embed.create - Create embeddings
• praisonai.moderate.check - Content moderation
• praisonai.rerank - Rerank documents
• praisonai.search - Web search

Memory Tools

• praisonai.memory.show - Show memory
• praisonai.memory.add - Add to memory
• praisonai.memory.search - Search memory
• praisonai.memory.clear - Clear memory

Knowledge Tools

• praisonai.knowledge.add - Add knowledge
• praisonai.knowledge.query - Query knowledge
• praisonai.knowledge.list - List sources
• praisonai.knowledge.clear - Clear knowledge

Rules Tools

• praisonai.rules.list - List active rules
• praisonai.rules.show(rule_name) - Show a specific rule
• praisonai.rules.create(rule_name, content) - Create a new rule
• praisonai.rules.delete(rule_name) - Delete a rule

Security: As of PraisonAI 4.6.34, rule names are validated to prevent path traversal attacks. Rule names must be single filenames (no /, \, .., leading ., or NUL bytes).

Rules Tool Examples

Valid rule names:

• "team-style.md" ✅
• "coding_standards.txt" ✅
• "PROJECT_RULES" ✅

Invalid rule names:

• "../../etc/passwd" ❌ (contains traversal)
• "subdir/rule.md" ❌ (contains directory separator)
• ".bashrc" ❌ (starts with dot)

For security details, see GHSA-9mqq-jqxf-grvw.

Available Resources

URI	Description
praisonai://memory/sessions	List memory sessions
praisonai://workflows	List available workflows
praisonai://tools	List available tools
praisonai://agents	List agent configurations
praisonai://knowledge/sources	List knowledge sources
praisonai://config	Get current configuration
praisonai://mcp/status	Get MCP server status

Available Prompts

Name	Description
deep-research	Generate deep research prompts
code-review	Generate code review prompts
workflow-auto	Generate workflow auto-generation prompts
guardrail-check	Generate guardrail check prompts
context-engineering	Generate context engineering prompts
eval-criteria	Generate evaluation criteria prompts
agent-instructions	Generate agent instructions prompts

Python API

from praisonai.mcp_server.server import MCPServer
from praisonai.mcp_server.adapters import register_all

# Register all tools, resources, and prompts
register_all()

# Create server
server = MCPServer(
    name="praisonai",
    version="1.0.0",
    instructions="PraisonAI MCP Server",
)

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

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

Custom Tools

Register custom tools:

from praisonai.mcp_server.registry import register_tool

@register_tool("custom.greet")
def greet(name: str) -> str:
    """Greet a person by name."""
    return f"Hello, {name}!"

Security

Path Traversal Protection: PraisonAI 4.6.34 includes hardening against path traversal attacks in MCP rules tools. See GHSA-9mqq-jqxf-grvw for details.

Origin Validation

For HTTP Stream transport, origin validation is enabled by default:

• Localhost binding: Only localhost origins allowed
• External binding: Requires explicit --allowed-origins configuration

Authentication

Use --api-key for Bearer token authentication:

praisonai mcp serve --transport http-stream --api-key YOUR_SECRET_KEY

Clients must include:

Authorization: Bearer YOUR_SECRET_KEY

Troubleshooting

Check Server Health

praisonai mcp doctor

Enable Debug Logging

praisonai mcp serve --log-level debug

Common Issues

1. “Missing dependency” - Install with pip install praisonai[mcp]
2. “No API keys configured” - Set OPENAI_API_KEY environment variable
3. “Origin validation failed” - Add origin to --allowed-origins