> ## 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.
# MCP Integration
> Connect agents to any MCP server for filesystem, database, and API tools
MCP (Model Context Protocol) lets agents connect to external tool servers, instantly adding file system access, database queries, API integrations, and more.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent, MCP
agent = Agent(
name="FileAgent",
instructions="You help users manage their files.",
tools=MCP("npx -y @modelcontextprotocol/server-filesystem /tmp"),
)
agent.start("List all files in the /tmp directory.")
```
The user asks to inspect the filesystem; the agent calls MCP tools on the connected server.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
subgraph "MCP Flow"
Agent[🤖 Agent] --> MCP[🔌 MCP Client]
MCP --> Server[🖥️ MCP Server]
Server --> Tools[🔧 Tools]
Tools --> Server
Server --> MCP
MCP --> Agent
end
classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
classDef mcp fill:#189AB4,stroke:#7C90A0,color:#fff
classDef server fill:#F59E0B,stroke:#7C90A0,color:#fff
classDef output fill:#10B981,stroke:#7C90A0,color:#fff
class Agent agent
class MCP mcp
class Server,Tools server
```
## Quick Start
```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 a file called notes.txt with the text 'Hello World'.")
```
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent, MCP
agent = Agent(
instructions="You can search and retrieve web content.",
tools=MCP("https://mcp.example.com/sse"),
)
agent.start("Search for the latest news about AI.")
```
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent, MCP
filesystem_tools = MCP("npx -y @modelcontextprotocol/server-filesystem /home/user")
database_tools = MCP("npx -y @modelcontextprotocol/server-sqlite /db/app.sqlite")
agent = Agent(
instructions="You manage files and database records.",
tools=[*filesystem_tools, *database_tools],
)
agent.start("Read the config file and update the database with its settings.")
```
***
## How It Works
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
participant User
participant Agent
participant MCP
participant Server
User->>Agent: Request
Agent->>MCP: Connect to server
MCP->>Server: Initialize + list tools
Server-->>MCP: Available tools
MCP-->>Agent: Tool definitions
Agent->>MCP: Call tool
MCP->>Server: Execute tool
Server-->>MCP: Result
MCP-->>Agent: Tool result
Agent-->>User: Response
```
| Phase | What happens |
| ----------- | ----------------------------------------------------- |
| 1. Connect | MCP client connects to the server on first use |
| 2. Discover | Server reports its available tools |
| 3. Execute | Agent calls tools via the MCP protocol |
| 4. Return | Results flow back through the MCP client to the agent |
***
## MCP Server Types
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
Q{What transport does the server use?}
Q -->|Command line| Stdio[stdio\nnpx / python command]
Q -->|HTTP streaming| SSE[SSE\nhttps://server/sse]
classDef decision fill:#F59E0B,stroke:#7C90A0,color:#fff
classDef type fill:#6366F1,stroke:#7C90A0,color:#fff
class Q decision
class Stdio,SSE type
```
***
## Common Patterns
### Pattern 1 — File management agent
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent, MCP
agent = Agent(
name="FileManager",
instructions="You help users organize and manage their files efficiently.",
tools=MCP("npx -y @modelcontextprotocol/server-filesystem /home/user/documents"),
)
response = agent.start("Find all PDF files and create a summary list.")
print(response)
```
### Pattern 2 — Database agent
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent, MCP
agent = Agent(
name="DBAgent",
instructions="You query and analyze database records.",
tools=MCP("npx -y @modelcontextprotocol/server-sqlite /path/to/database.sqlite"),
)
agent.start("Show me all users who signed up in the last 30 days.")
```
### Pattern 3 — GitHub integration
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent, MCP
import os
agent = Agent(
name="GitHubAgent",
instructions="You help manage GitHub repositories and issues.",
tools=MCP(
"npx -y @modelcontextprotocol/server-github",
env={"GITHUB_PERSONAL_ACCESS_TOKEN": os.environ["GITHUB_TOKEN"]},
),
)
agent.start("List the 5 most recent open issues in my repository.")
```
***
## Best Practices
Start with the official `@modelcontextprotocol` npm packages for common integrations (filesystem, SQLite, GitHub, etc.). They're well-tested and actively maintained.
When using the filesystem MCP server, pass the narrowest directory path you need. Giving access to `/` or `/home` when you only need `/app/data` creates unnecessary risk.
Never hardcode API keys or tokens in your code. Pass them as environment variables to the MCP server via the `env` parameter, and source them from your environment or secrets manager.
Agents can use tools from multiple MCP servers simultaneously. Unpack each server's tools with `*MCP(...)` and combine them into a single `tools` list for maximum capability. Loading via [`load_mcp_tools`](/docs/features/load-mcp-tools) auto-namespaces each server's tools (e.g. `filesystem_search`, `github_search`) so overlapping names never collide.
***
## Related
Tools — built-in tools and custom tool functions
MCP Tool Filtering — filter which tools to expose per agent