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

• 80+ MCP Tools – Access all PraisonAI capabilities as MCP tools (86 registered by praisonai-mcp serve)
• 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

Three pathways install the heavy MCP host.

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

# Or via the umbrella product
pip install "praisonai[mcp]"

CLI Commands

Start Server

The standalone praisonai-mcp console script and the umbrella praisonai mcp form are equivalent for all host commands.

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

# HTTP Stream transport
praisonai-mcp serve --transport http-stream --port 8080
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

The three discovery commands share the same registration surface as serve and doctor — anything serve exposes at runtime shows up here:

# List available tools (86 registered)
praisonai-mcp list-tools          # or: praisonai mcp list-tools

# List available resources (7 registered)
praisonai mcp list-resources

# List available prompts (7 registered)
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

# Pretty (default)
praisonai-mcp doctor              # or: praisonai mcp doctor

# Machine-readable — safe for CI, safe on Windows cp1252 consoles
praisonai-mcp doctor --json       # or: praisonai mcp doctor --json

See the full doctor reference for the JSON payload shape, exit codes, and error output.

Server Options

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-mcp",
      "args": ["serve", "--transport", "stdio"]
    }
  }
}

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

Cursor

Add to Cursor MCP settings:

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

{
  "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(source) — add a knowledge source (file path, URL, or raw text). No source_type needed; the store auto-detects.
• praisonai.knowledge.query – Query knowledge
• praisonai.knowledge.list – List sources
• praisonai.knowledge.clear — clear the knowledge base. Returns "Knowledge cleared" only when the configured backend actually reset. When the backend does not support reset() (e.g. ChromaKnowledgeAdapter), the tool returns `”Error: knowledge was NOT cleared – the configured backend (

) does not support reset()”` — a truthful failure on a destructive path.

• praisonai.knowledge.stats – Corpus statistics

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

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

Available 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

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

STDIO Transport Reliability

The STDIO transport (praisonai-mcp serve --transport stdio) is hardened to work everywhere your MCP client runs and to survive bad input and shutdown.

• Runs on Windows too — including Windows + Python 3.13, which used to crash. The host reads stdin on a dedicated background thread (named mcp-stdio-reader) instead of the async pipe API, so it no longer fails with OSError: [WinError 6] The handle is invalid when Cursor, Claude Desktop, or Windsurf spawn it with redirected pipes.
• Bad input never kills the server — malformed (non-UTF-8) bytes become a JSON-RPC parse error (-32700) and the server keeps running.
• Bounded input queue — incoming lines are capped at 1000 with backpressure, so a fast or hostile client can’t grow memory without limit.
• Clean shutdown — stopping the server (Ctrl+C or client disconnect) wakes a reader that is blocked on idle-but-open stdin, so it never hangs.

Troubleshooting

Error semantics

A tool response with isError: true means the call failed — either the adapter raised, or it returned an "Error: …" string that the host now surfaces as an error. MCP clients, routers, and retry logic can rely on this field. Adapters that succeed always return isError: false.

Check Server Health

praisonai mcp doctor

Enable Debug Logging

praisonai mcp serve --log-level debug

Clients can also raise the log level at runtime via the JSON-RPC logging/setLevel method. This scopes to the same per-server praisonai.mcp_server.<name> logger, and requires the admin scope when scoped API keys are configured.

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