đ« CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org
Python agentai-societiesartificial-intelligencecommunicative-aicooperative-aideep-learninglarge-language-modelsmulti-agent-systemsnatural-language-processing
docs: Add MCP Section (#2777)
Sarthak Bhardwaj16e90dbdcb02
diff --git a/docs/mintlify/docs.json b/docs/mintlify/docs.jsonindex 7106ad175..30a6a47fc 100644--- a/docs/mintlify/docs.json+++ b/docs/mintlify/docs.json@@ -72,15 +72,25 @@"key_modules/retrievers"]},+ {+ "group": "CAMEL with MCP",+ "pages": [+ "mcp/overview",+ "mcp/camel_agents_as_an_mcp_clients",+ "mcp/export_camel_agent_as_mcp_server",+ "mcp/camel_toolkits_as_an_mcp_server",+ "mcp/mcp_hub"+ ]+ },{"group": "Cookbooks","pages": [{"group": "Basic Concepts","pages": [+ "cookbooks/basic_concepts/create_your_first_agent","cookbooks/basic_concepts/agents_message","cookbooks/basic_concepts/agents_prompting",- "cookbooks/basic_concepts/create_your_first_agent","cookbooks/basic_concepts/create_your_first_agents_society","cookbooks/basic_concepts/model_speed_comparison"]@@ -101,7 +111,7 @@"cookbooks/advanced_features/critic_agents_and_tree_search","cookbooks/advanced_features/embodied_agents"]- },+ },{"group": "Applications","pages": [diff --git a/docs/mintlify/images/camel_toolks_as_mcp_server.png b/docs/mintlify/images/camel_toolks_as_mcp_server.pngnew file mode 100644index 000000000..884f754bdBinary files /dev/null and b/docs/mintlify/images/camel_toolks_as_mcp_server.png differdiff --git a/docs/mintlify/images/claude_example1.png b/docs/mintlify/images/claude_example1.pngnew file mode 100644index 000000000..0194f0a3eBinary files /dev/null and b/docs/mintlify/images/claude_example1.png differdiff --git a/docs/mintlify/images/claude_example2.png b/docs/mintlify/images/claude_example2.pngnew file mode 100644index 000000000..5ac3a0994Binary files /dev/null and b/docs/mintlify/images/claude_example2.png differdiff --git a/docs/mintlify/images/mcp-architecture.jpeg b/docs/mintlify/images/mcp-architecture.jpegnew file mode 100644index 000000000..17fde6194Binary files /dev/null and b/docs/mintlify/images/mcp-architecture.jpeg differdiff --git a/docs/mintlify/images/mcp-client-server-example.png b/docs/mintlify/images/mcp-client-server-example.pngnew file mode 100644index 000000000..8b1152826Binary files /dev/null and b/docs/mintlify/images/mcp-client-server-example.png differdiff --git a/docs/mintlify/images/mcp-without-vs-with.jpg b/docs/mintlify/images/mcp-without-vs-with.jpgnew file mode 100644index 000000000..29b656996Binary files /dev/null and b/docs/mintlify/images/mcp-without-vs-with.jpg differdiff --git a/docs/mintlify/mcp/camel_agents_as_an_mcp_clients.mdx b/docs/mintlify/mcp/camel_agents_as_an_mcp_clients.mdxnew file mode 100644index 000000000..b217c214a--- /dev/null+++ b/docs/mintlify/mcp/camel_agents_as_an_mcp_clients.mdx@@ -0,0 +1,194 @@+---+title: "CAMEL Agents as an MCP Client"+icon: plug+---++This guide walks you through turning your CAMEL AI agent into an MCP client, letting your agent easily use tools from multiple MCP servers.++## Quick Setup Steps++1. **Create a Config File**: Tell CAMEL which MCP servers you want to connect to.+2. **Use MCPToolkit to Connect**: Load your config file to connect to the servers.+3. **Enable Tools in CAMEL Agent**: Pass the server tools to your CAMEL agent to use.++This guide walks you through turning your CAMEL AI agent into an MCP client, letting your agent easily use tools from multiple MCP servers.++## Step-by-Step Setup++<Steps>++ <Step title="Step 1: Configure MCP Servers">+ Start by creating a config file that tells your CAMEL agent what MCP servers to connect to. You can define local or remote servers, each with a transport method.++ <Tabs>+ <Tab title="Local Server (stdio)">+ ```json+ {+ "mcpServers": {+ "time_server": {+ "command": "python",+ "args": ["time_server.py"],+ "transport": "stdio"+ }+ }+ }+ ```+ </Tab>++ <Tab title="Remote Server (streamable-http, sse)">+ ```json+ {+ "mcpServers": {+ "composio-notion": {+ "command": "npx",+ "args": ["composio-core@rc", "mcp", "https://mcp.composio.dev/notion/your-server-id", "--client", "camel"],+ "env": {+ "COMPOSIO_API_KEY": "your-api-key-here"+ },+ "transport": "streamable-http"+ }+ }+ }+ ```+ </Tab>+ <Tab title="ACI.dev Server (configurable transport)">+ ```json+ {+ "mcpServers": {+ "aci_apps": {+ "command": "uvx",+ "args": [+ "aci-mcp",+ "apps-server",+ "--apps=BRAVE_SEARCH,GITHUB,ARXIV",+ "--linked-account-owner-id",+ "<your_linked_acc_owner_id>"+ ],+ "env": {+ "ACI_API_KEY": "your_aci_api_key"+ },+ "transport": "sse" // or "streamable-http"+ }+ }+ }+ ```+ <Note type="info">+You can use <code>sse</code> or <code>streamable-http</code> for ACI.dev, pick whichever is supported by your agent/server.+</Note>+ </Tab>+++ </Tabs>+ </Step>++ <Step title="Step 2: Connect & Build the Agent">+ Use `MCPToolkit` to connect to the servers and pass the tools to your CAMEL agent.++ ```python+ import asyncio+ from camel.toolkits.mcp_toolkit import MCPToolkit+ from camel.agents import ChatAgent++ async def main():+ async with MCPToolkit(config_path="config/time.json") as toolkit:+ agent = ChatAgent(model=model, tools=toolkit.get_tools())+ response = await agent.astep("What time is it now?")+ print(response.msgs[0].content)++ asyncio.run(main())+ ```+ </Step>++ <Step title="Step 3: Add More Tools & Debug">+ Once connected, you can extend your setup with other servers from ACI.dev, Composio, or `npx`.++ <Note type="info">+ - Use `stdio` for local testing, `sse` or `streamable-http` for cloud tools.+ - Secure your API keys using the `env` field in the config.+ - Use the MCP Inspector (`npx @modelcontextprotocol/inspector`) if you run into issues.++ Try plugging in servers like GitHub, Notion, or ArXiv and see your CAMEL agent in action.+ </Note>+ </Step>++</Steps>++## How It Works â System Diagram++<Card title="CAMEL Agent as an MCP Client" img="/images/camel_toolks_as_mcp_server.png">+This diagram illustrates how CAMEL agents use MCPToolkit to seamlessly connect with MCP servers. Servers provide external tools from platforms like GitHub, Gmail, Notion, and more.+</Card>++<Card title="Advanced: Register with MCP Hubs & Registries">++<Card title="Connect your agent to an MCP registry" icon="link">+Want your MCP agent discoverable by thousands of clients?+Register it with a hub like <a href="https://aci.dev/" target="_blank">ACI.dev</a> or similar.+```python Register with ACI Registry lines icon="python"+from camel.agents import MCPAgent+from camel.types import ACIRegistryConfig, ModelFactory, ModelPlatformType, ModelType+import os++aci_config = ACIRegistryConfig(+ api_key=os.getenv("ACI_API_KEY"),+ linked_account_owner_id=os.getenv("ACI_LINKED_ACCOUNT_OWNER_ID"),+)+model = ModelFactory.create(+ model_platform=ModelPlatformType.OPENAI,+ model_type=ModelType.GPT_4O,+)++agent = MCPAgent(+ model=model,+ registry_configs=[aci_config],+)+```+Your agent is now connected to the <a href="https://aci.dev/" target="_blank">ACI.dev</a> registry and visible in the ecosystem.+</Card>++<Card title = "Discover MCP Servers Easily with PulseMCP">++Finding MCP servers is now a breeze with PulseMCP integration.+You donât have to guess which MCP servers are available, just search, browse, and connect.++<Card title="Discover MCP Servers Instantly" icon="wave-pulse">+PulseMCP acts as a living directory of the entire MCP ecosystem.+CAMEL toolkits can plug directly into PulseMCP, letting you browse and connect to thousands of servers, all kept up to date in real time.++You can visit [PulseMCP.com](https://pulsemcp.com) to browse all available MCP serversâeverything from file systems and search to specialized APIs.++If you prefer to search programmatically inside your CAMEL code, just use:++<CodeBlock language="python" title="pulse_mcp_search.py">+from camel.toolkits.mcp import PulseMCPSearchToolkit++search_toolkit = PulseMCPSearchToolkit()+results = search_toolkit.search_mcp_servers(query="Slack", top_k=1)+print(results)+</CodeBlock>++PulseMCP does the heavy lifting of finding, categorizing, and keeping MCP servers freshâyour agents just connect and go.+</Card>+</Card>++<Card title="Minimal agent without function-calling" icon="function">+Donât need advanced tool-calling?+See <a href="https://github.com/camel-ai/camel/blob/master/examples/agents/mcp_agent/mcp_agent_without_function_calling.py" target="_blank">this example</a> for a super-lightweight setup.+</Card>+</Card>++## Using Transport Methods++- **stdio**: Ideal for local servers. Fast and easy.+- **sse**: Great for cloud-hosted servers like ACI.dev.+- **streamable-http**: Recommended for modern cloud integrations.++## Tips to Keep in Mind++- For easiest troubleshooting, try with a simple local stdio server first; once youâre comfortable, you can connect to cloud servers using sse or streamable-http.+- Store your API keys securely in the config file, never in code.+- Use the MCP Inspector tool (`npx @modelcontextprotocol/inspector`) for debugging.++## Give It a Go++Try setting up a config file for an MCP server (like [GitHub](https://github.com/github/github-mcp-server) or [Notion](https://github.com/makenotion/notion-mcp-server)) and see your CAMEL agent use the new tools right away!diff --git a/docs/mintlify/mcp/camel_toolkits_as_an_mcp_server.mdx b/docs/mintlify/mcp/camel_toolkits_as_an_mcp_server.mdxnew file mode 100644index 000000000..1e038fe76--- /dev/null+++ b/docs/mintlify/mcp/camel_toolkits_as_an_mcp_server.mdx@@ -0,0 +1,69 @@+---+title: "Toolkit as MCP Server"+icon: "server"+description: "Share any CAMEL toolkit as an MCP server so external clients and agents can use your tools."+---++<CardGroup cols={2}>++ <Card title="What is a Toolkit?" icon="screwdriver-wrench">+ A <b>Toolkit</b> is a bundle of related toolsâfunctions that let agents fetch data, automate, search, or integrate with services.+ <br />+ <a href="/key_modules/tools"><b>Browse all CAMEL toolkits â</b></a>+ </Card>++ <Card title="Toolkit as an MCP Server" icon="head-side-gear">+ With one command, you can flip any toolkit into an <b>MCP server</b>.+ Now, any MCP-compatible client or agent can call your toolsâlocally or over the network.+ </Card>++</CardGroup>++## Quick Example++<Card title="Run Any Toolkit as an MCP Server" icon="rocket">++You can turn any CAMEL toolkit into a full-featured MCP serverâmaking its tools instantly available to other AI agents or external apps via the Model Context Protocol.++<b>Why do this?</b>+- Instantly share your agent tools with external clients (e.g., Claude, Cursor, custom dashboards).+- Enable distributed, language-agnostic tool execution across different systems and teams.+- Easily test, debug, and reuse your toolsâno need to change the toolkit or agent code.++### Launch a Toolkit Server++Below is a minimal script to expose <b>ArxivToolkit</b> as an MCP server.+Swap in any other toolkit (e.g., <code>SearchToolkit</code>, <code>MathToolkit</code>), they all work the same way!++<CodeBlock language="python" title="arxiv_toolkit_server.py">+from camel.toolkits import ArxivToolkit+import argparse++parser = argparse.ArgumentParser(+ description="Run Arxiv Toolkit as an MCP server."+)+parser.add_argument(+ "--mode",+ choices=["stdio", "sse", "streamable-http"],+ default="stdio",+ help="Select MCP server mode."+)+args = parser.parse_args()++toolkit = ArxivToolkit()+toolkit.mcp.run(args.mode)+</CodeBlock>++- **stdio:** For local IPC (default, fast and secure for single-machine setups)+- **sse:** Server-Sent Events (good for remote servers and web clients)+- **streamable-http:** Modern, high-performance HTTP streaming++### Discoverable & Usable Instantly++Once running, your MCP server will:+- Advertise all available toolkit methods as standard MCP tools+- Support <b>dynamic tool discovery</b> (`tools/list` endpoint)+- Allow <b>any compatible agent or client</b> (not just CAMEL) to connect and call your tools++This means you can build an LLM workflow where, for example, Claude running in your browser or another service in your company network can call your toolkit directlyâwithout ever importing your Python code.+</Card>diff --git a/docs/mintlify/mcp/export_camel_agent_as_mcp_server.mdx b/docs/mintlify/mcp/export_camel_agent_as_mcp_server.mdxnew file mode 100644index 000000000..c64c7c22b--- /dev/null+++ b/docs/mintlify/mcp/export_camel_agent_as_mcp_server.mdx@@ -0,0 +1,99 @@+---+title: "CAMEL Agent as an MCP Server"+icon: server+description: "Turn your CAMEL ChatAgent into an MCP serverâlet any client (Claude, Cursor, custom apps) connect and use your agent as a universal AI backend."+---++<Card title="Why export a ChatAgent as an MCP server?" icon="server">+Publishing your <b>ChatAgent</b> as an MCP server turns your agent into a universal AI backend.+Any MCP-compatible client (Claude, Cursor, editors, or your own app) can connect, chat, and run tools through your agent as if it were a native APIâno custom integration required.+</Card>++## Quick Start++<Card>++<Card title="Method 1: Use Service Scripts" icon="terminal">+<b>Scripted Server:</b>+Launch your agent as an MCP server with the ready-made scripts in <code>services/</code>.+Configure your MCP client (Claude, Cursor, etc.) to connect:+```json mcp_servers_config.json Example highlight={5}+{+ "camel-chat-agent": {+ "command": "/path/to/python",+ "args": [+ "/path/to/camel/services/agent_mcp_server.py"+ ],+ "env": {+ "OPENAI_API_KEY": "...",+ "OPENROUTER_API_KEY": "...",+ "BRAVE_API_KEY": "..."+ }+ }+}+```+<Info>+<b>Tip:</b> Just point your MCP client at this config, and it will auto-discover and call your agent!+</Info>+</Card>++<Card title="Method 2: Use `to_mcp()`" icon="bolt">+Turn any <code>ChatAgent</code> into an MCP server instantly with <code>to_mcp()</code>:+```python agent_mcp_server.py lines icon="python"+from camel.agents import ChatAgent++# Create a chat agent with your model+agent = ChatAgent(model="gpt-4o-mini")++# Convert to an MCP server+mcp_server = agent.to_mcp(+ name="demo", description="A demonstration of ChatAgent to MCP conversion"+)++if __name__ == "__main__":+ print("Starting MCP server on http://localhost:8000")+ mcp_server.run(transport="streamable-http")+```+<Info>+<b>Supported transports:</b> <code>stdio</code>, <code>sse</code>, <code>streamable-http</code>+</Info>+</Card>++</Card>+++<Card title="What does this unlock?" icon="unlock">+- **Plug-and-play with any MCP client**: Claude, Cursor, editors, automationsâjust connect and go.+- **Universal API**: Your agent becomes an âAI APIâ for any tool that speaks MCP.+- **Security & Flexibility**: Keep control over keys, environments, and agent configs.+</Card>++## Real-world Example++<Card title="Claude calling a CAMEL MCP server" icon="comments">+You can use Claude, Cursor, or any other app to call your custom agent!+Just connect to your <b>CAMEL MCP server</b>+<img src="/images/claude_example1.png" alt="Claude MCP Screenshot" />+<img src="/images/claude_example2.png" alt="Claude MCP Screenshot" />+<Info>+You can expose any number of custom tools, multi-agent workflows, or domain knowledge, right from your own laptop or server!+</Info>+</Card>++---++## Why make your ChatAgent an MCP server?++<Card title="Benefits" icon="star">+- **Universal Access:** Any client, any platform, anytime.+- **Multi-Agent Workflows:** Power agent societies by letting agents call each other.+- **Local Control:** Expose only the tools and data you want, with full security.+- **No Glue Code:** MCP handles discovery and invocation, no custom REST or RPC needed.+</Card>++---++<Info>+Want to create your own tools and toolkits?+See <a href="/key_modules/tools">Toolkits Reference</a> for everything you can expose to the MCP ecosystem!+</Info>diff --git a/docs/mintlify/mcp/mcp_hub.mdx b/docs/mintlify/mcp/mcp_hub.mdxnew file mode 100644index 000000000..4cc77dfc6--- /dev/null+++ b/docs/mintlify/mcp/mcp_hub.mdx@@ -0,0 +1,5 @@+---+title: "CAMEL-AI MCPHub"+icon: warehouse+url: "https://mcp.camel-ai.org/"+---\ No newline at end of filediff --git a/docs/mintlify/mcp/overview.mdx b/docs/mintlify/mcp/overview.mdxnew file mode 100644index 000000000..e2ebcb79b--- /dev/null+++ b/docs/mintlify/mcp/overview.mdx@@ -0,0 +1,103 @@+---+title: 'Overview'+description: 'Introduction to MCP: what it is, why it matters, and how it transforms agent integration.'+icon: 'play'+---++## What is MCP all about?++MCP (Model Context Protocol) originated from an [Anthropic article](https://www.anthropic.com/news/model-context-protocol) published on November 25, 2024: *Introducing the Model Context Protocol*.++MCP defines **how applications and AI models exchange contextual information**.+It enables developers to connect data sources, tools, and functions to LLMs using a universal, standardized protocolâmuch like USB-C enables diverse devices to connect via a single interface.++<CardGroup cols={2}>+ <Card title="Universal Standard" icon="universal-access">+ MCP aims to be the "USB-C for AI": one protocol, endless integrations. Plug in any tool or data sourceâLLM models just work with it.+ </Card>+ <Card title="Layer of Abstraction" icon="layer-group">+ Sits between LLMs and external tools/data, so you can add capabilities and context without changing agent code.+ </Card>+ <Card title="Flexible & Language-Agnostic" icon="language">+ MCP servers can be built in any language, run anywhere, and connect to anythingâfrom cloud APIs to local files.+ </Card>+ <Card title="Consistent Developer Experience" icon="puzzle">+ Write your agent logic once, then extend it with new plugins or data via MCP, just by registering a new server.+ </Card>+</CardGroup>++## Visualizing MCP++Hereâs how MCP acts as an **intermediate protocol layer** between LLMs and tools:++<Frame caption="Visualization of MCP as an intermediate layer between LLMs and tools">+ <img src="/images/mcp-architecture.jpeg" />+</Frame>++## What Changes with MCP?++<Frame caption="With MCP, tools and models connect through a single protocol instead of point-to-point integrations">+ <img src="/images/mcp-without-vs-with.jpg" />+</Frame>++## Why introduce MCP?++- **Ecosystem**: Leverage a growing library of MCP pluginsâjust plug them in.+- **Uniformity**: Not limited to any one model or vendor; if your agent supports MCP, you can swap models/tools anytime.+- **Data Security**: Keep sensitive data on your device. MCP servers decide what to exposeâyour private data never needs to leave your machine.++## MCP Architecture and Principles++**Basic Architecture**++MCP follows a **client-server model** with three main roles:++<CardGroup cols={3}>+ <Card title="MCP Host" icon="message-quote">+ Applications like Claude Desktop, IDEs, or AI tools that need external data/tools. The "Host" is the user-facing app.+ </Card>+ <Card title="MCP Client" icon="signal-stream">+ Built into the Host, the MCP Client manages protocol communication and connects to MCP Servers.+ </Card>+ <Card title="MCP Server" icon="server">+ Lightweight services (local or remote) that expose specific functions (e.g., read files, search web) via the MCP protocol.+ </Card>+</CardGroup>++- **Local Data Sources**: Files, folders, databases, and services MCP servers can securely access.+- **Remote Services**: Online APIs and cloud platforms accessible to MCP servers.+++### How it works, step by step:++1. **User asks:**+ âWhat documents do I have on my desktop?â via the Host (e.g., Claude Desktop).++2. **Host (MCP Host):**+ Receives your question and forwards it to the Claude model.++3. **Client (MCP Client):**+ Claude model decides it needs more data, Client is activated to connect to a file system MCP Server.++4. **Server (MCP Server):**+ The server reads your desktop directory and returns a list of documents.++5. **Results:**+ Claude uses this info to answer your question, displayed in your desktop app.++This architecture **lets agents dynamically call tools and access data**âlocal or remoteâwhile developers only focus on building the relevant MCPServer.+**You donât have to handle the nitty-gritty of connecting Hosts and Clients.**++<Note type="info">+For deeper architecture details and diagrams, see the+<a href="https://modelcontextprotocol.io/docs/concepts/architecture" target="_blank">official MCP docs: Architecture Concepts</a>.+</Note>++## At a Glance++- **MCP** standardizes and simplifies agent-to-tool connections.+- **Developers** build or reuse MCP servers, not custom integrations for every agent.+- **Users** get safer, more flexible, and privacy-friendly AI workflows.++---+