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

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

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    subgraph "Three MCP Layers"
        C[📋 MCP Client<br/>praisonaiagents/mcp<br/>Connect to external MCP servers]
        L[🟠 Light Server<br/>praisonai-code / praisonai serve mcp<br/>Basic ToolsMCPServer]
        H[⚙️ Heavy Host<br/>praisonai-mcp<br/>Full MCPServer + adapters + auth]
    end

    classDef client fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef light fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef heavy fill:#8B0000,stroke:#7C90A0,color:#fff

    class C client
    class L light
    class H heavy
```

## Which Layer Do I Need?

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    Q{What do I want to do?}
    Q -->|Connect my agent to<br/>an external MCP server| C["praisonaiagents[mcp]<br/>MCP client"]
    Q -->|Serve a small tool set<br/>from config| L["praisonai-code<br/>praisonai serve mcp"]
    Q -->|Serve full capabilities /<br/>recipes with auth| H["praisonai-mcp<br/>praisonai-mcp serve"]

    classDef question fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef client fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef light fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef heavy fill:#8B0000,stroke:#7C90A0,color:#fff

    class Q question
    class C client
    class L light
    class H heavy
```

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

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
pip install praisonai-code
praisonai serve mcp
```

### Heavy host

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

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
pip install "praisonai-mcp[all]"
praisonai-mcp serve --transport stdio
```

***

## Best Practices

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Heavy host for auth and recipes">
    Reach for `praisonai-mcp` when you need OAuth 2.1 / OIDC, HTTP-stream transport, or recipe serving.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="praisonai-mcp Package" icon="plug" href="/docs/features/praisonai-mcp-package">
    Standalone heavy-host package guide.
  </Card>

  <Card title="MCP Integration" icon="plug" href="/docs/features/mcp">
    Connect agents to external MCP servers.
  </Card>

  <Card title="PraisonAI MCP Server" icon="server" href="/docs/mcp/praisonai-mcp-server">
    Heavy MCP host reference.
  </Card>

  <Card title="Package Tiers" icon="layer-group" href="/docs/features/architecture-tiers">
    How the seven packages stack.
  </Card>
</CardGroup>