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

Install Dependencies

bash

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

# Or the full PraisonAI stack
pip install "praisonai[mcp]"

Set API Key
bash
```
export OPENAI_API_KEY="your-key"
```

Start MCP Server

bash

praisonai-mcp serve --transport stdio
praisonai mcp serve --transport stdio   # equivalent (umbrella)

Serving Your Own Agents

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

python

from praisonaiagents import Agent
from praisonai_mcp import serve_agents

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

See Serve Agents for the full guide.

CLI – STDIO Transport

For Claude Desktop, Cursor, Windsurf local integration:

bash

praisonai-mcp serve --transport stdio
praisonai mcp serve --transport stdio   # equivalent

CLI – HTTP Stream Transport

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

bash

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

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

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

# 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

Claude Desktop Output:

Standalone (praisonai-mcp)

json

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

Umbrella (praisonai)

json

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

Connect MCP Client

Claude Desktop (claude_desktop_config.json):

For STDIO:

Standalone (praisonai-mcp)

json

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

Umbrella (praisonai)

json

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

For HTTP Stream:

json

{
  "mcpServers": {
    "praisonai": {
      "url": "http://localhost:8080/mcp",
      "transport": "http-stream"
    }
  }
}

Cursor (.cursor/mcp.json):

Standalone (praisonai-mcp)

json

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

Umbrella (praisonai)

json

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

List Available Tools

bash

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.

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.

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; 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 for the record shape and store resolution.

Search Tools

bash

# 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

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

praisonai mcp serve --transport http-stream --api-key mykey --port 8080

Client config with auth:

json

{
  "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

Serve Agents – Publish your own agents as ask_{name} tools
praisonai-mcp Package – Standalone host package guide
The Three MCP Layers – Client vs light server vs heavy host
Tools MCP – Deploy tools as MCP server
Agents MCP – Deploy agents as MCP server
Recipes MCP – Deploy recipes as MCP server

Server: PraisonAI MCP

Quick Start

Serving Your Own Agents

CLI – STDIO Transport

CLI – HTTP Stream Transport

CLI Options

Python SDK

Constants

MCP Protocol Features

Generate Client Config

Standalone (praisonai-mcp)

Umbrella (praisonai)

Connect MCP Client

Standalone (praisonai-mcp)

Umbrella (praisonai)

Standalone (praisonai-mcp)

Umbrella (praisonai)

List Available Tools

Agent Tools

Memory Tools

Todo Tools

Search Tools

Health Check

Authentication

Troubleshooting

Related