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

# 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

<Steps>
  <Step title="Install Dependencies">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # Standalone MCP host
    pip install "praisonai-mcp[all]"

    # Or the full PraisonAI stack
    pip install "praisonai[mcp]"
    ```
  </Step>

  <Step title="Set API Key">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    export OPENAI_API_KEY="your-key"
    ```
  </Step>

  <Step title="Start MCP Server">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai-mcp serve --transport stdio
    praisonai mcp serve --transport stdio   # equivalent (umbrella)
    ```
  </Step>
</Steps>

<Note>
  `praisonai-mcp serve …` (standalone) and `praisonai mcp serve …` (umbrella) are equivalent for host commands. See the [praisonai-mcp Package](/docs/docs/features/praisonai-mcp-package) guide and [The Three MCP Layers](/docs/docs/features/mcp-three-layers).
</Note>

## CLI - STDIO Transport

For Claude Desktop, Cursor, Windsurf local integration:

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

<Note>
  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](/docs/docs/mcp/praisonai-mcp-server#stdio-transport-reliability) section.
</Note>

## CLI - HTTP Stream Transport

For remote access (MCP 2025-11-25 spec):

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

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

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

<Note>
  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.
</Note>

**Claude Desktop Output:**

<Tabs>
  <Tab title="Standalone (praisonai-mcp)">
    ```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    {
      "mcpServers": {
        "praisonai": {
          "command": "praisonai-mcp",
          "args": ["serve", "--transport", "stdio"]
        }
      }
    }
    ```
  </Tab>

  <Tab title="Umbrella (praisonai)">
    ```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    {
      "mcpServers": {
        "praisonai": {
          "command": "praisonai",
          "args": ["mcp", "serve", "--transport", "stdio"]
        }
      }
    }
    ```
  </Tab>
</Tabs>

## Connect MCP Client

**Claude Desktop** (`claude_desktop_config.json`):

For STDIO:

<Tabs>
  <Tab title="Standalone (praisonai-mcp)">
    ```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    {
      "mcpServers": {
        "praisonai": {
          "command": "praisonai-mcp",
          "args": ["serve", "--transport", "stdio"]
        }
      }
    }
    ```
  </Tab>

  <Tab title="Umbrella (praisonai)">
    ```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    {
      "mcpServers": {
        "praisonai": {
          "command": "praisonai",
          "args": ["mcp", "serve", "--transport", "stdio"]
        }
      }
    }
    ```
  </Tab>
</Tabs>

For HTTP Stream:

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

**Cursor** (`.cursor/mcp.json`):

<Tabs>
  <Tab title="Standalone (praisonai-mcp)">
    ```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    {
      "mcpServers": {
        "praisonai": {
          "command": "praisonai-mcp",
          "args": ["serve", "--transport", "stdio"]
        }
      }
    }
    ```
  </Tab>

  <Tab title="Umbrella (praisonai)">
    ```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    {
      "mcpServers": {
        "praisonai": {
          "command": "praisonai",
          "args": ["mcp", "serve", "--transport", "stdio"]
        }
      }
    }
    ```
  </Tab>
</Tabs>

## List Available Tools

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

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

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

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

Client config with auth:

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "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](/docs/docs/features/praisonai-mcp-package) - Standalone host package guide
* [The Three MCP Layers](/docs/docs/features/mcp-three-layers) - Client vs light server vs heavy host
* [Tools MCP](./tools-mcp) - Deploy tools as MCP server
* [Agents MCP](./agents-mcp) - Deploy agents as MCP server
* [Recipes MCP](./recipes-mcp) - Deploy recipes as MCP server