> ## 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/features/praisonai-mcp-package) guide and [The Three MCP Layers](/docs/features/mcp-three-layers).
</Note>

## Serving Your Own Agents

To publish *your* agents (not the built-in throwaway assistant), use `serve_agents([...])`.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
from praisonai_mcp import serve_agents

serve_agents([Agent(name="Support", instructions="Help users.")], port=7777)
```

See [Serve Agents](/docs/features/serve-agents) for the full guide.

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

## Constants

`praisonai_mcp` exports two module-level naming constants (in `__all__`). They back forthcoming session-listing and approval-over-MCP features and keep the vocabulary consistent with the SDK's `list_*` verb style.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import praisonai_mcp

praisonai_mcp.SESSION_LIST_TOOL         # "list_sessions"
praisonai_mcp.STATUS_AWAITING_APPROVAL  # "awaiting_approval"
```

| Constant | Value | Meaning |
| - | - | - |
| `SESSION_LIST_TOOL` | `"list_sessions"` | Tool name for listing sessions — matches the SDK's `list_*` verb style. |
| `STATUS_AWAITING_APPROVAL` | `"awaiting_approval"` | Run status telling you *why* a run stopped. |

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

## Agent Tools

The built-in agent tools run a generic, server-owned assistant proxy — not your agents.

| Tool | Arguments | Description |
| - | - | - |
| `praisonai.agent.chat` | `message`, `model` | Chat one turn with the built-in assistant. |
| `praisonai.agent.run` | `task`, `model` | Run a one-off task with the built-in assistant. |

<Warning>
  The `instructions=` parameter was **removed** from `praisonai.agent.chat` and `praisonai.agent.run` in PR #3531 (fixes #3528). A connecting client can no longer rewrite the assistant's persona — the server owns it. To publish *your* agents with *your* persona, use [`serve_agents([...])`](/docs/features/serve-agents).
</Warning>

## Memory Tools

The memory tools call the real core memory API.

| Tool | Arguments | Description |
| - | - | - |
| `praisonai.memory.show` | `user_id?` | Show stored memory, optionally filtered by `user_id`. |
| `praisonai.memory.add` | `content`, `metadata?` | Store a short-term memory entry. |
| `praisonai.memory.search` | `query`, `limit=10`, `user_id?` | Search stored memory. |
| `praisonai.memory.clear` | — | Clears **all** memory (short-term + long-term) via `reset_all()`. No per-session clear. |

<Note>
  `praisonai.memory.sessions` was removed in PR #3531 — the tool no longer exists.
</Note>

## Todo Tools

The todo tools read and write the **same** store as the agent runtime — `<workspace>/todos.json` if a workspace is active, else `~/.praisonai/todos.json`. Rebound to the runtime store in PraisonAI PR [#4962](https://github.com/MervinPraison/PraisonAI/pull/4962); before that they used the wrong path `~/.praison/todo.json` in an incompatible schema.

| Tool | Arguments | Description |
| - | - | - |
| `praisonai.todo.list` | — | List every todo. Returns `"No todos found"` when the store is empty. |
| `praisonai.todo.add` | `content`, `priority="medium"` | Append a todo. Returns `"Todo added: <id>"` (integer id, starts at `1`). |
| `praisonai.todo.complete` | `todo_id` | Mark the matching todo `completed`. Returns `"Todo not found: <id>"` if no match. |
| `praisonai.todo.delete` | `todo_id` | Delete the matching todo. Returns `"Todo not found: <id>"` if no match. |

See [MCP Todo Tools](/docs/features/mcp-todo-tools) for the record shape and store resolution.

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

* [Serve Agents](/docs/features/serve-agents) - Publish your own agents as `ask_{name}` tools
* [praisonai-mcp Package](/docs/features/praisonai-mcp-package) - Standalone host package guide
* [The Three MCP Layers](/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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.