mirror of
https://github.com/mcp-use/mcp-use.git
synced 2026-09-14 18:06:01 +08:00
pietrozullo
ad42b4bb3e
The searchable: false approach on the API Reference tab was inert on visible tabs. Switch to per-page noindex: true frontmatter, which keeps pages in the sidebar but excludes them from search indexing (search engines, internal docs search, and AI context) so generic queries like "CLI" surface curated guides instead of the generated reference. Applied to all 73 existing reference pages and emitted by the generator on every regeneration. Closes MCP-2398
354 lines
14 KiB
Plaintext
354 lines
14 KiB
Plaintext
---
|
|
title: "Mcpagent"
|
|
description: "MCP: Main integration module with customizable system prompt API Documentation"
|
|
icon: "code"
|
|
github: "https://github.com/mcp-use/mcp-use/blob/main/libraries/python/mcp_use/agents/mcpagent.py"
|
|
noindex: true
|
|
---
|
|
|
|
import {RandomGradientBackground} from "/snippets/gradient.jsx"
|
|
|
|
<Callout type="info" title="Source Code">
|
|
View the source code for this module on GitHub: <a href='https://github.com/mcp-use/mcp-use/blob/main/libraries/python/mcp_use/agents/mcpagent.py' target='_blank' rel='noopener noreferrer'>https://github.com/mcp-use/mcp-use/blob/main/libraries/python/mcp_use/agents/mcpagent.py</a>
|
|
</Callout>
|
|
|
|
MCP: Main integration module with customizable system prompt.
|
|
|
|
This module provides the main MCPAgent class that integrates all components
|
|
to provide a simple interface for using MCP tools with different LLMs.
|
|
|
|
LangChain 1.0.0 Migration:
|
|
- The agent uses create_agent() from langchain.agents which returns a CompiledStateGraph
|
|
- New methods: astream_simplified() and run_v2() leverage the built-in astream() from
|
|
CompiledStateGraph which handles the agent loop internally
|
|
- Legacy methods: stream() and run() use manual step-by-step execution for backward compatibility
|
|
|
|
## MCPAgent
|
|
|
|
<div>
|
|
<RandomGradientBackground className="rounded-lg p-4 w-full h-full rounded-full">
|
|
<div className="text-black">
|
|
<div className="text-black font-bold text-xl mb-2 mt-8"><code className="!text-black">class</code> MCPAgent</div>
|
|
|
|
Main class for using MCP tools with various LLM providers.
|
|
|
|
This class provides a unified interface for using MCP tools with different LLM providers
|
|
through LangChain's agent framework, with customizable system prompts and conversation memory.
|
|
|
|
</div>
|
|
</RandomGradientBackground>
|
|
```python
|
|
from mcp_use.agents.mcpagent import MCPAgent
|
|
```
|
|
|
|
<Card type="info">
|
|
### `method` __init__
|
|
|
|
Initialize a new MCPAgent instance.
|
|
|
|
|
|
**Parameters**
|
|
><ParamField body="llm" type="langchain_core.language_models.base.BaseLanguageModel | None" default="None" > The LangChain LLM to use. Not required if agent_id is provided for remote execution. </ParamField>
|
|
><ParamField body="client" type="mcp_use.client.client.MCPClient | None" default="None" > The MCPClient to use. If provided, connector is ignored. </ParamField>
|
|
><ParamField body="connectors" type="list[mcp_use.client.connectors.base.BaseConnector] | None" default="None" > A list of MCP connectors to use if client is not provided. </ParamField>
|
|
><ParamField body="max_steps" type="int" default="5" > The maximum number of steps to take. </ParamField>
|
|
><ParamField body="auto_initialize" type="bool" default="False" > Whether to automatically initialize the agent when run is called. </ParamField>
|
|
><ParamField body="memory_enabled" type="bool" default="True" > Whether to maintain conversation history for context. </ParamField>
|
|
><ParamField body="system_prompt" type="str | None" default="None" > Complete system prompt to use (overrides template if provided). </ParamField>
|
|
><ParamField body="system_prompt_template" type="str | None" default="None" > Template for system prompt with {tool_descriptions} placeholder. </ParamField>
|
|
><ParamField body="additional_instructions" type="str | None" default="None" > Extra instructions to append to the system prompt. </ParamField>
|
|
><ParamField body="disallowed_tools" type="list[str] | None" default="None" > List of tool names that should not be available to the agent. </ParamField>
|
|
><ParamField body="tools_used_names" type="list[str] | None" default="None" > List of tools </ParamField>
|
|
><ParamField body="use_server_manager" type="bool" default="False" > Whether to use server manager mode instead of exposing all tools. </ParamField>
|
|
><ParamField body="server_manager" type="mcp_use.agents.managers.base.BaseServerManager | None" default="None" > Server name or configuration </ParamField>
|
|
><ParamField body="verbose" type="bool" default="False" > Enable debug/verbose mode </ParamField>
|
|
><ParamField body="pretty_print" type="bool" default="False" > Whether to pretty print the output. </ParamField>
|
|
><ParamField body="agent_id" type="str | None" default="None" > Remote agent ID for remote execution. If provided, creates a remote agent. </ParamField>
|
|
><ParamField body="api_key" type="str | None" default="None" > API key for remote execution. If None, checks MCP_USE_API_KEY env var. </ParamField>
|
|
><ParamField body="base_url" type="str" default='https://cloud.manufact.com' > Base URL for remote API calls. </ParamField>
|
|
><ParamField body="callbacks" type="list | None" default="None" > List of LangChain callbacks to use. If None and Langfuse is configured, uses langfuse_handler. </ParamField>
|
|
><ParamField body="chat_id" type="str | None" default="None" > String value </ParamField>
|
|
><ParamField body="retry_on_error" type="bool" default="True" > Whether to enable automatic error handling for tool calls. When True, tool errors </ParamField>
|
|
|
|
**Signature**
|
|
```python wrap
|
|
def __init__(llm: langchain_core.language_models.base.BaseLanguageModel | None = None, client: mcp_use.client.client.MCPClient | None = None, connectors: list[mcp_use.client.connectors.base.BaseConnector] | None = None, max_steps: int = 5, auto_initialize: bool = False, memory_enabled: bool = True, system_prompt: str | None = None, system_prompt_template: str | None = None, additional_instructions: str | None = None, disallowed_tools: list[str] | None = None, tools_used_names: list[str] | None = None, use_server_manager: bool = False, server_manager: mcp_use.agents.managers.base.BaseServerManager | None = None, verbose: bool = False, pretty_print: bool = False, agent_id: str | None = None, api_key: str | None = None, base_url: str = "https://cloud.manufact.com", callbacks: list | None = None, chat_id: str | None = None, retry_on_error: bool = True):
|
|
```
|
|
|
|
</Card>
|
|
<Card type="info">
|
|
### `method` add_to_history
|
|
|
|
Add a message to the conversation history.
|
|
|
|
|
|
|
|
**Parameters**
|
|
><ParamField body="message" type="langchain_core.messages.base.BaseMessage" required="True" > The message to add. </ParamField>
|
|
|
|
**Signature**
|
|
```python wrap
|
|
def add_to_history(message: langchain_core.messages.base.BaseMessage):
|
|
```
|
|
|
|
</Card>
|
|
|
|
<Card type="info">
|
|
### `method` clear_conversation_history
|
|
|
|
Clear the conversation history.
|
|
|
|
|
|
**Signature**
|
|
```python wrap
|
|
def clear_conversation_history():
|
|
```
|
|
|
|
</Card>
|
|
|
|
<Card type="info">
|
|
### `method` close
|
|
|
|
Close the MCP connection with improved error handling.
|
|
|
|
|
|
**Signature**
|
|
```python wrap
|
|
def close():
|
|
```
|
|
|
|
</Card>
|
|
|
|
<Card type="info">
|
|
### `method` get_conversation_history
|
|
|
|
Get the current conversation history.
|
|
|
|
|
|
|
|
**Returns**
|
|
><ResponseField name="returns" type="list[langchain_core.messages.base.BaseMessage]" >The list of conversation messages.</ResponseField>
|
|
|
|
**Signature**
|
|
```python wrap
|
|
def get_conversation_history():
|
|
```
|
|
|
|
</Card>
|
|
|
|
<Card type="info">
|
|
### `method` get_disallowed_tools
|
|
|
|
Get the list of tools that are not available to the agent.
|
|
|
|
|
|
|
|
**Returns**
|
|
><ResponseField name="returns" type="list[str]" >List of tool names that are not available.</ResponseField>
|
|
|
|
**Signature**
|
|
```python wrap
|
|
def get_disallowed_tools():
|
|
```
|
|
|
|
</Card>
|
|
|
|
<Card type="info">
|
|
### `method` get_system_message
|
|
|
|
Get the current system message.
|
|
|
|
|
|
|
|
**Returns**
|
|
><ResponseField name="returns" type="langchain_core.messages.system.SystemMessage | None" >The current system message, or None if not set.</ResponseField>
|
|
|
|
**Signature**
|
|
```python wrap
|
|
def get_system_message():
|
|
```
|
|
|
|
</Card>
|
|
|
|
<Card type="info">
|
|
### `method` initialize
|
|
|
|
Initialize the MCP client and agent.
|
|
|
|
|
|
**Signature**
|
|
```python wrap
|
|
def initialize():
|
|
```
|
|
|
|
</Card>
|
|
|
|
<Card type="info">
|
|
### `method` run
|
|
|
|
Run a query using LangChain 1.0.0's agent and return the final result.
|
|
|
|
Example:
|
|
```python
|
|
# Regular usage
|
|
result = await agent.run("What's the weather like?")
|
|
|
|
# Structured output usage
|
|
from pydantic import BaseModel, Field
|
|
|
|
class WeatherInfo(BaseModel):
|
|
temperature: float = Field(description="Temperature in Celsius")
|
|
condition: str = Field(description="Weather condition")
|
|
|
|
weather: WeatherInfo = await agent.run(
|
|
"What's the weather like?",
|
|
output_schema=WeatherInfo
|
|
)
|
|
```
|
|
|
|
|
|
**Parameters**
|
|
><ParamField body="query" type="str | langchain_core.messages.human.HumanMessage" required="True" > The query to run. Accepts a plain string or a ``HumanMessage`` when </ParamField>
|
|
><ParamField body="max_steps" type="int | None" default="None" > Optional maximum number of steps to take. </ParamField>
|
|
><ParamField body="manage_connector" type="bool" default="True" > Whether to handle the connector lifecycle internally. </ParamField>
|
|
><ParamField body="external_history" type="list[langchain_core.messages.base.BaseMessage] | None" default="None" > Optional external history to use instead of the </ParamField>
|
|
><ParamField body="output_schema" type="type[~T] | None" default="None" > Optional Pydantic BaseModel class for structured output. </ParamField>
|
|
|
|
**Returns**
|
|
><ResponseField name="returns" type="str | mcp_use.agents.mcpagent.T" >The result of running the query as a string, or if output_schema is provided, an instance of the specified Pydantic model.</ResponseField>
|
|
|
|
**Signature**
|
|
```python wrap
|
|
def run(
|
|
query: str | langchain_core.messages.human.HumanMessage,
|
|
max_steps: int | None = None,
|
|
manage_connector: bool = True,
|
|
external_history: list[langchain_core.messages.base.BaseMessage] | None = None,
|
|
output_schema: type[~T] | None = None
|
|
):
|
|
```
|
|
|
|
</Card>
|
|
|
|
<Card type="info">
|
|
### `method` set_disallowed_tools
|
|
|
|
Set the list of tools that should not be available to the agent.
|
|
|
|
This will take effect the next time the agent is initialized.
|
|
|
|
|
|
|
|
**Parameters**
|
|
><ParamField body="disallowed_tools" type="list[str]" required="True" > List of tool names that should not be available. </ParamField>
|
|
|
|
**Signature**
|
|
```python wrap
|
|
def set_disallowed_tools(disallowed_tools: list[str]):
|
|
```
|
|
|
|
</Card>
|
|
|
|
<Card type="info">
|
|
### `method` set_system_message
|
|
|
|
Set a new system message.
|
|
|
|
|
|
|
|
**Parameters**
|
|
><ParamField body="message" type="str" required="True" > The new system message content. </ParamField>
|
|
|
|
**Signature**
|
|
```python wrap
|
|
def set_system_message(message: str):
|
|
```
|
|
|
|
</Card>
|
|
|
|
<Card type="info">
|
|
### `method` stream
|
|
|
|
Async generator using LangChain 1.0.0's create_agent and astream.
|
|
|
|
This method leverages the LangChain 1.0.0 API where create_agent returns
|
|
a CompiledStateGraph that handles the agent loop internally via astream.
|
|
|
|
**Tool Updates with Server Manager:**
|
|
When using server_manager mode, this method handles dynamic tool updates:
|
|
- **Before execution:** Updates are applied immediately to the new stream
|
|
- **During execution:** When tools change, we wait for a "safe restart point"
|
|
(after tool results complete), then interrupt the stream, recreate the agent
|
|
with new tools, and resume execution with accumulated messages.
|
|
- **Safe restart points:** Only restart after tool results to ensure message
|
|
pairs (tool_use + tool_result) are complete, satisfying LLM API requirements.
|
|
- **Max restarts:** Limited to 3 restarts to prevent infinite loops
|
|
|
|
This interrupt-and-restart approach ensures that tools added mid-execution
|
|
(e.g., via connect_to_mcp_server) are immediately available to the agent,
|
|
maintaining the same behavior as the legacy implementation while respecting
|
|
API constraints.
|
|
|
|
Yields:
|
|
Intermediate steps and final result from the agent execution.
|
|
|
|
|
|
**Parameters**
|
|
><ParamField body="query" type="str | langchain_core.messages.human.HumanMessage" required="True" > The query to run. Accepts a plain string or a ``HumanMessage`` when </ParamField>
|
|
><ParamField body="max_steps" type="int | None" default="None" > Integer value </ParamField>
|
|
><ParamField body="manage_connector" type="bool" default="True" > Whether to handle the connector lifecycle internally. </ParamField>
|
|
><ParamField body="external_history" type="list[langchain_core.messages.base.BaseMessage] | None" default="None" > Optional external history to use instead of the </ParamField>
|
|
><ParamField body="track_execution" type="bool" default="True" > Boolean flag </ParamField>
|
|
><ParamField body="output_schema" type="type[~T] | None" default="None" > Optional Pydantic BaseModel class for structured output. </ParamField>
|
|
|
|
**Returns**
|
|
><ResponseField name="returns" type="AsyncGenerator" />
|
|
|
|
**Signature**
|
|
```python wrap
|
|
def stream(
|
|
query: str | langchain_core.messages.human.HumanMessage,
|
|
max_steps: int | None = None,
|
|
manage_connector: bool = True,
|
|
external_history: list[langchain_core.messages.base.BaseMessage] | None = None,
|
|
track_execution: bool = True,
|
|
output_schema: type[~T] | None = None
|
|
):
|
|
```
|
|
|
|
</Card>
|
|
|
|
<Card type="info">
|
|
### `method` stream_events
|
|
|
|
Asynchronous streaming interface.
|
|
|
|
Example::
|
|
|
|
async for chunk in agent.stream_events("hello"):
|
|
print(chunk)
|
|
|
|
|
|
**Parameters**
|
|
><ParamField body="query" type="str | langchain_core.messages.human.HumanMessage" required="True" > Query string or input </ParamField>
|
|
><ParamField body="max_steps" type="int | None" default="None" > Integer value </ParamField>
|
|
><ParamField body="manage_connector" type="bool" default="True" > Connector instance </ParamField>
|
|
><ParamField body="external_history" type="list[langchain_core.messages.base.BaseMessage] | None" default="None" > List of items </ParamField>
|
|
|
|
**Returns**
|
|
><ResponseField name="returns" type="AsyncIterator" />
|
|
|
|
**Signature**
|
|
```python wrap
|
|
def stream_events(
|
|
query: str | langchain_core.messages.human.HumanMessage,
|
|
max_steps: int | None = None,
|
|
manage_connector: bool = True,
|
|
external_history: list[langchain_core.messages.base.BaseMessage] | None = None
|
|
):
|
|
```
|
|
|
|
</Card>
|
|
|
|
</div>
|