MCP Server CLI Commands

PraisonAI provides comprehensive CLI commands for running and managing MCP servers.

The MCP server host ships as the standalone praisonai-mcp package. Every praisonai mcp serve … example below also runs as praisonai-mcp serve … — both forms are equivalent for host commands. See The Three MCP Layers for how the host fits.

Primary Command

praisonai-mcp <subcommand> [options]   # standalone console script
praisonai mcp <subcommand> [options]   # equivalent (umbrella)

Subcommands

list-tools, list-resources, list-prompts, serve, and doctor all share the same register_all() registration — anything serve exposes at runtime shows up in the corresponding list-* command (see sibling parity fix #2146).

serve

Start the MCP server.

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

# HTTP Stream transport
praisonai-mcp serve --transport http-stream

# With all options
praisonai mcp serve \
  --transport http-stream \
  --host 127.0.0.1 \
  --port 8080 \
  --endpoint /mcp \
  --api-key YOUR_KEY \
  --name praisonai \
  --response-mode batch \
  --session-ttl 3600 \
  --log-level info

Options:

Option	Description	Default
`--transport`	`stdio` or `http-stream`	`stdio`
`--host`	Server host	`127.0.0.1`
`--port`	Server port	`8080`
`--endpoint`	MCP endpoint path	`/mcp`
`--api-key`	API key for authentication (single wildcard-scoped key)	None
`--keys-file`	JSON file of per-key scopes for least-privilege access	None
`--name`	Server name	`praisonai`
`--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`	`debug`, `info`, `warning`, `error`	`warning`
`--json`	Output in JSON format	False
`--debug`	Enable debug mode	False

Use --keys-file for per-team, least-privilege scoped keys. See Scoped API keys for the JSON format, the operation→scope map, and the insufficient_scope response.

list-tools

List all available MCP tools.

praisonai mcp list-tools

Example Output:

Available MCP Tools (86):

  • praisonai.chat.completion
    Generate chat completion.

  • praisonai.agent.chat
    Chat with a PraisonAI agent.

  • praisonai.images.generate
    Generate images from text prompt.
  ...

list-resources

List all available MCP resources.

praisonai mcp list-resources

Example Output:

Available MCP Resources (7):

  • praisonai://memory/sessions
    List all memory sessions.

  • praisonai://workflows
    List available workflows in current directory.
  ...

The list-resources / list-prompts commands correctly print the registered entries as of PraisonAI v4.6.154. On earlier releases the two commands returned "No resources registered" / "No prompts registered" even when doctor reported 7 of each — see upstream PR #3220. Upgrade with pip install -U "praisonai-mcp[all]" (or pip install -U "praisonai[mcp]") if you see the old empty output.

list-prompts

List all available MCP prompts.

praisonai mcp list-prompts

Example Output:

Available MCP Prompts (7):

  • deep-research
    Generate a deep research prompt for comprehensive topic analysis

  • code-review
    Generate a code review prompt for analyzing code quality
  ...

Same version cutover as list-resources: list-prompts prints the 7 registered prompts as of PraisonAI v4.6.154. Earlier releases printed "No prompts registered" even when doctor reported 7 — see upstream PR #3220.

config-generate

Generate client configuration for MCP clients.

# Claude Desktop config
praisonai mcp config-generate --client claude-desktop

# Cursor config
praisonai mcp config-generate --client cursor

# VSCode config
praisonai mcp config-generate --client vscode

# Windsurf config
praisonai mcp config-generate --client windsurf

# Save to file
praisonai mcp config-generate --client claude-desktop --output config.json

# HTTP Stream config
praisonai mcp config-generate --client claude-desktop --transport http-stream --port 8080

Options:

Option	Description	Default
`--client`	Client type	`claude-desktop`
`--output`	Output file path	stdout
`--transport`	Transport type	`stdio`
`--host`	Server host (for http-stream)	`127.0.0.1`
`--port`	Server port (for http-stream)	`8080`

Output: Since v4.6.154, the generator auto-detects praisonai-mcp on your PATH and emits the matching STDIO command.

Standalone (praisonai-mcp)
Umbrella (praisonai)

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

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

doctor

Health check for the MCP server. Human-readable by default, or machine-readable with --json.

# Pretty (default)
praisonai mcp doctor

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

Flag	Effect
`--json`	Machine-readable JSON output (no Unicode symbols, safe for CI)

Example Output (text):

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

Example Output (--json):

{
  "protocol_version": "2025-11-25",
  "supported_versions": ["2025-11-25", "2025-03-26", "2024-11-05"],
  "components": {
    "tools": 86,
    "resources": 7,
    "prompts": 7
  },
  "environment": {
    "OPENAI_API_KEY": true,
    "ANTHROPIC_API_KEY": false,
    "GOOGLE_API_KEY": false
  },
  "dependencies": {
    "starlette": true,
    "uvicorn": true,
    "praisonaiagents": true
  },
  "ready": true
}

JSON-mode failures still emit valid JSON, so CI parsers never choke on Rich-formatted text:

{
  "error": "register blew up",
  "ready": false
}

On Windows consoles using a legacy code page (e.g. cp1252), doctor falls back to ASCII markers ([OK], [--], [X]) instead of the Unicode ✓ ○ ✗ — so it never crashes with UnicodeEncodeError. Add --json for automation on any platform; it never emits Unicode symbols. This mirrors the umbrella praisonai doctor status-symbol handling.

Deprecated Commands

The following commands are deprecated and will be removed in a future version:

# DEPRECATED - use 'praisonai mcp serve' instead
praisonai serve mcp

# DEPRECATED - use 'praisonai mcp serve' instead
praisonai serve tools

These commands will show a deprecation warning and redirect to praisonai mcp serve.

Examples

Start STDIO Server for Claude Desktop

praisonai mcp serve --transport stdio

Start HTTP Server with Authentication

praisonai mcp serve \
  --transport http-stream \
  --port 8080 \
  --api-key mysecretkey

Start Server with Custom Origins

praisonai mcp serve \
  --transport http-stream \
  --allowed-origins "http://localhost:3000,https://myapp.com"

Generate and Apply Claude Desktop Config

# Generate config
praisonai mcp config-generate --client claude-desktop --output ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Or manually copy the output
praisonai mcp config-generate --client claude-desktop

Debug Mode

praisonai mcp serve --transport http-stream --debug --log-level debug

Environment Variables

Variable	Description
`OPENAI_API_KEY`	OpenAI API key for chat/image tools
`ANTHROPIC_API_KEY`	Anthropic API key
`GOOGLE_API_KEY`	Google API key

Exit Codes

Code	Description
0	Success — all dependencies present and at least one API key configured
1	Error — any dependency missing, or any exception raised

In doctor --json mode, missing API keys alone (with all dependencies present) still exit 0 — only a missing dependency or an exception exits 1.

Common Issues

Issue	Fix
`praisonai-mcp list-resources` or `list-prompts` prints “No resources/prompts registered”	Upgrade to v4.6.154 or later — the registries were being read before being populated on those subcommands (PR #3220).

​MCP Server CLI Commands

​Primary Command

​Subcommands

​serve

​list-tools

​list-resources

​list-prompts

​config-generate

​doctor

​Deprecated Commands

​Examples

​Start STDIO Server for Claude Desktop

​Start HTTP Server with Authentication

​Start Server with Custom Origins

​Generate and Apply Claude Desktop Config

​Debug Mode

​Environment Variables

​Exit Codes

​Common Issues

​See Also

MCP Server CLI Commands

Primary Command

Subcommands

serve

list-tools

list-resources

list-prompts

config-generate

doctor

Deprecated Commands

Examples

Start STDIO Server for Claude Desktop

Start HTTP Server with Authentication

Start Server with Custom Origins

Generate and Apply Claude Desktop Config

Debug Mode

Environment Variables

Exit Codes

Common Issues

See Also