The Three MCP Layers

Client, light server, and heavy host — which MCP package you need and when

PraisonAI has three distinct MCP roles across three packages — connecting to servers, serving a small tool set, and hosting the full capability registry.

from praisonaiagents import Agent, MCP

agent = Agent(
    name="assistant",
    instructions="Use connected tools to help the user.",
    tools=MCP("npx -y @modelcontextprotocol/server-filesystem /tmp"),
)
agent.start("List files in /tmp.")

The snippet above is the client layer. Serving your own agents uses the light or heavy layer instead.

Which Layer Do I Need?

The Layers

Each layer maps to one package and one job.

Layer	Package	Install	Role
Client	praisonaiagents/mcp/	pip install "praisonaiagents[mcp]"	Connect agents to external MCP servers
Light server	praisonai-code	pip install praisonai-code	Config-driven basic tool hosting (ToolsMCPServer)
Heavy host	praisonai-mcp	pip install "praisonai-mcp[all]"	Full MCPServer, adapters, recipe bridge, HTTP-stream auth

Client

Connect an agent to any external MCP server and use its tools.

from praisonaiagents import Agent, MCP

agent = Agent(
    instructions="You can read and write files.",
    tools=MCP("npx -y @modelcontextprotocol/server-filesystem /tmp"),
)
agent.start("Create notes.txt with 'Hello World'.")

Light server

Serve a small, config-driven tool set from the terminal CLI.

pip install praisonai-code
praisonai serve mcp

Heavy host

Serve the full PraisonAI capability registry, recipes, and auth.

pip install "praisonai-mcp[all]"
praisonai-mcp serve --transport stdio

---

Best Practices

Client for consuming, host for serving

Use the agents-tier MCP class to consume external tools. Use praisonai-mcp to expose your own agents to MCP clients.

Light server for a fixed tool set

praisonai serve mcp is the lightest way to publish a handful of config-driven tools without the heavy host.

Heavy host for auth and recipes

Reach for praisonai-mcp when you need OAuth 2.1 / OIDC, HTTP-stream transport, or recipe serving.

---

Related

praisonai-mcp Package

Standalone heavy-host package guide.

MCP Integration

Connect agents to external MCP servers.

PraisonAI MCP Server

Heavy MCP host reference.

Package Tiers

How the seven packages stack.