<!-- source: https://deepwiki.com/MervinPraison/PraisonAI/5.2-mcp-protocol -->

# MCP Protocol

- README.md
- docker/Dockerfile
- docker/Dockerfile.chat
- docker/Dockerfile.dev
- docker/Dockerfile.ui
- docker/README.md
- src/praisonai-agents/pyproject.toml
- src/praisonai-agents/uv.lock
- src/praisonai/README.md
- src/praisonai/praisonai.rb
- src/praisonai/praisonai/cli/main.py
- src/praisonai/praisonai/deploy.py
- src/praisonai/praisonai/version.py
- src/praisonai/pyproject.toml
- src/praisonai/uv.lock

## Purpose and Scope

The Model Context Protocol (MCP) is a standardized protocol implemented in PraisonAI for exposing and consuming AI tools across different systems. MCP enables agents to interact with external tool servers and exposes PraisonAI's own tools as MCP-compatible servers. This page documents both client mode (consuming external MCP servers) and server mode (exposing PraisonAI tools to external clients), as well as the supported transport mechanisms.

For general tool integration patterns, see [Tool Integration](/MervinPraison/PraisonAI/5.1-tool-integration). For agent-to-agent communication using a different protocol, see [A2A Protocol](/MervinPraison/PraisonAI/5.3-a2a-protocol).

## MCP Architecture Overview

### System Design

```

```

**Sources:** [README.md349-356](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L349-L356) [src/praisonai-agents/pyproject.toml23-28](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/pyproject.toml#L23-L28)

### Dual Operating Modes

PraisonAI implements MCP in two distinct modes:

**Sources:** [README.md351-355](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L351-L355)

## Client Mode: Consuming MCP Servers

### Purpose

Client mode allows PraisonAI agents to consume tools provided by external MCP servers. This enables agents to access filesystem operations, database queries, API integrations, and other capabilities exposed by MCP-compatible servers without implementing the tools directly.

### Architecture

```

```

**Sources:** [README.md355](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L355-L355)

### Configuration

MCP client configuration is stored in `.praison/mcp_config.json` or managed via CLI commands:

```

```

**Sources:** [README.md355](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L355-L355) [src/praisonai/pyproject.toml19](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/pyproject.toml#L19-L19)

### Transport Support

**Sources:** [src/praisonai-agents/pyproject.toml23-28](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/pyproject.toml#L23-L28)

### Dependencies

Client mode requires the `mcp` optional dependency group:

```

```

This installs:

- mcp>=1.20.0 - Core MCP protocol library
- fastapi>=0.115.0 - HTTP server support
- uvicorn>=0.34.0 - ASGI server
- websockets>=12.0 - WebSocket transport

**Sources:** [src/praisonai-agents/pyproject.toml23-28](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/pyproject.toml#L23-L28)

## Server Mode: Exposing Tools as MCP

### Purpose

Server mode allows PraisonAI to expose its tools and agents as MCP-compatible servers. This enables external MCP clients (like Claude Desktop, Cursor, or other AI applications) to discover and invoke PraisonAI's capabilities.

### Architecture

```

```

**Sources:** [README.md352-354](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L352-L354)

### Exposing Agent Tools

PraisonAI agents can expose their tools as MCP servers using built-in server mode. When an agent is configured as an MCP server, its tools become discoverable and callable by external MCP clients.

### Server Transport Options

SSE (Server-Sent Events) transport is particularly useful for:

- Web-based integrations
- Long-running connections
- Resumable sessions
- Real-time streaming responses

**Sources:** [README.md352-354](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L352-L354) [src/praisonai-agents/pyproject.toml23-28](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/pyproject.toml#L23-L28)

### MCP Registry

PraisonAI is registered in the official MCP Registry, allowing it to be discovered and used by MCP-compatible clients:

- Registry ID: io.github.MervinPraison/praisonai
- Badge: MCP Registry compatible

**Sources:** [README.md9](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L9-L9) [README.md15](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L15-L15)

## Transport Types

### Transport Comparison

```

```

**Sources:** [README.md351](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L351-L351) [src/praisonai-agents/pyproject.toml23-28](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/pyproject.toml#L23-L28)

### stdio Transport

**Characteristics:**

- Process-to-process communication via standard input/output
- Lowest latency for local tools
- Requires process spawning
- Stateful connection (process lifetime)

**Use Cases:**

- Local desktop applications
- CLI tools
- Development and testing

**Configuration Pattern:**

```

```

**Sources:** [README.md351](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L351-L351)

### HTTP Transport

**Characteristics:**

- RESTful API communication
- Stateless request/response
- Requires FastAPI server
- Supports authentication and CORS

**Use Cases:**

- Remote tool servers
- Microservices architecture
- Cloud deployments

**Dependencies:** Requires `fastapi>=0.115.0` and `uvicorn>=0.34.0`

**Sources:** [src/praisonai-agents/pyproject.toml25-26](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/pyproject.toml#L25-L26)

### WebSocket Transport

**Characteristics:**

- Bidirectional real-time communication
- Persistent connection
- Supports streaming responses
- Lower overhead than HTTP for frequent calls

**Use Cases:**

- Real-time collaborative tools
- Streaming data processing
- Interactive applications

**Dependencies:** Requires `websockets>=12.0`

**Sources:** [README.md352](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L352-L352) [src/praisonai-agents/pyproject.toml27](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/pyproject.toml#L27-L27)

### SSE (Server-Sent Events) Transport

**Characteristics:**

- Unidirectional server-to-client streaming
- HTTP-based, firewall-friendly
- Automatic reconnection
- Supports resumability

**Use Cases:**

- Browser-based clients
- Progress updates and notifications
- Long-running operations
- Resumable sessions

**Advantages:**

- Works through standard HTTP infrastructure
- Built-in browser support via EventSource API
- Simpler than WebSocket for one-way streaming

**Sources:** [README.md354](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L354-L354) [src/praisonai-agents/pyproject.toml26](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/pyproject.toml#L26-L26)

## MCP Configuration Management

### Configuration File Location

MCP configuration is stored in:

- Per-project: .praison/mcp_config.json
- Global: ~/.praison/mcp_config.json

Project-specific configuration takes precedence over global configuration.

**Sources:** [README.md355](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L355-L355)

### CLI Configuration Commands

```

```

**Sources:** [README.md355](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L355-L355)

### Configuration Schema

The MCP configuration file follows the standard MCP server configuration format:

```

```

**Sources:** [README.md355](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L355-L355) [src/praisonai-agents/pyproject.toml23-28](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/pyproject.toml#L23-L28)

## MCP Security

### Security Features

```

```

**Sources:** [README.md353](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L353-L353)

### Authentication

MCP supports multiple authentication mechanisms:

**Sources:** [README.md353](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L353-L353)

### Transport Security

- HTTP/SSE: Use HTTPS with TLS certificates
- WebSocket: Use WSS (WebSocket Secure)
- stdio: Relies on OS-level process isolation

**Sources:** [src/praisonai-agents/pyproject.toml23-28](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/pyproject.toml#L23-L28)

## MCP Resumability

### Session Management

SSE transport supports resumable sessions, allowing clients to reconnect and continue from where they left off:

```

```

**Sources:** [README.md354](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L354-L354)

### Checkpoint Support

The resumability feature integrates with PraisonAI's checkpoint system to ensure consistent state across reconnections:

- Session state is persisted in checkpoints
- Clients can resume from specific checkpoints
- Failed operations can be retried without data loss

**Sources:** [README.md354](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L354-L354)

## Integration with Agents

### Agent Tool Discovery

```

```

**Sources:** [README.md351-356](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L351-L356)

### Tool Registration

Agents automatically discover and register MCP tools from configured servers. The integration is transparent:

1. Agent loads MCP configuration from .praison/mcp_config.json
2. MCP client connects to configured servers
3. Available tools are registered in the agent's tool registry
4. Agent can invoke MCP tools alongside local tools

**Sources:** [README.md355](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L355-L355)

### Execution Flow

When an agent uses an MCP tool:

1. Agent decides to use a tool based on instructions/planning
2. Tool registry identifies the tool as MCP-sourced
3. MCP client sends tool invocation to external server
4. External server executes and returns result
5. Result is passed back to agent for further processing

**Sources:** [README.md351-352](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L351-L352)

## Dependencies and Installation

### Core Dependencies

The MCP protocol implementation in PraisonAI relies on:

```

```

**Sources:** [src/praisonai/pyproject.toml19](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/pyproject.toml#L19-L19) [src/praisonai-agents/pyproject.toml23-28](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/pyproject.toml#L23-L28)

### Installation

```

```

**Sources:** [src/praisonai-agents/pyproject.toml23-28](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/pyproject.toml#L23-L28) [src/praisonai/pyproject.toml19](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/pyproject.toml#L19-L19)

### Docker Support

MCP is included in all PraisonAI Docker images:

- Dockerfile.ui - UI service with MCP support
- Dockerfile.chat - Chat service with MCP support
- Dockerfile.dev - Development environment with MCP tools

**Sources:** [docker/Dockerfile.ui16-21](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/Dockerfile.ui#L16-L21) [docker/Dockerfile.chat16-21](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/Dockerfile.chat#L16-L21) [docker/Dockerfile.dev20-35](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/Dockerfile.dev#L20-L35)

## Related Documentation

- Tool Integration: See Tool Integration for general tool patterns including @tool decorator and BaseTool class
- A2A Protocol: See A2A Protocol for agent-to-agent communication protocol
- Custom Tools: See Custom Tools and Plugins for creating MCP-compatible tool plugins

**Sources:** [README.md349-358](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L349-L358)
