> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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)

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai mcp serve --transport stdio
```

### HTTP Stream Transport

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
pip install praisonai[mcp]
```

## CLI Commands

### Start Server

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# List available tools
praisonai mcp list-tools

# List available resources
praisonai mcp list-resources

# List available prompts
praisonai mcp list-prompts
```

### Generate Client Config

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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):

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "mcpServers": {
    "praisonai": {
      "command": "praisonai",
      "args": ["mcp", "serve", "--transport", "stdio"]
    }
  }
}
```

### Cursor

Add to Cursor MCP settings:

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "mcpServers": {
    "praisonai": {
      "command": "praisonai",
      "args": ["mcp", "serve", "--transport", "stdio"]
    }
  }
}
```

### HTTP Stream Client

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "mcpServers": {
    "praisonai": {
      "url": "http://127.0.0.1:8080/mcp",
      "transport": "http-stream"
    }
  }
}
```

## Environment Variables

Set these for full functionality:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

<Warning>
  **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).
</Warning>

#### 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](https://github.com/advisories/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

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

<Warning>
  **Path Traversal Protection**: PraisonAI 4.6.34 includes hardening against path traversal attacks in MCP rules tools. See [GHSA-9mqq-jqxf-grvw](https://github.com/advisories/GHSA-9mqq-jqxf-grvw) for details.
</Warning>

### 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:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai mcp serve --transport http-stream --api-key YOUR_SECRET_KEY
```

Clients must include:

```
Authorization: Bearer YOUR_SECRET_KEY
```

## Troubleshooting

### Check Server Health

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai mcp doctor
```

### Enable Debug Logging

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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`