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

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

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

​PraisonAI MCP Server

​Protocol Version

​Quick Start

​STDIO Transport (Recommended for Claude Desktop)

​HTTP Stream Transport

​Features

​Installation

​CLI Commands

​Start Server

​List Components

​Generate Client Config

​Health Check

​Server Options

​Client Configuration

​Claude Desktop

​Cursor

​HTTP Stream Client

​Environment Variables

​Available Tools

​Agent Tools

​Capability Tools

​Memory Tools

​Knowledge Tools

​Rules Tools

​Rules Tool Examples

​Available Resources

​Available Prompts

​Python API

​Custom Tools

​Security

​Origin Validation

​Authentication

​Troubleshooting

​Check Server Health

​Enable Debug Logging

​Common Issues

PraisonAI MCP Server

Protocol Version

Quick Start

STDIO Transport (Recommended for Claude Desktop)

HTTP Stream Transport

Features

Installation

CLI Commands

Start Server

List Components

Generate Client Config

Health Check

Server Options

Client Configuration

Claude Desktop

Cursor

HTTP Stream Client

Environment Variables

Available Tools

Agent Tools

Capability Tools

Memory Tools

Knowledge Tools

Rules Tools

Rules Tool Examples

Available Resources

Available Prompts

Python API

Custom Tools

Security

Origin Validation

Authentication

Troubleshooting

Check Server Health

Enable Debug Logging

Common Issues