Skip to content

armgit / camel

Public Imported from GitHub
0

đŸ« CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org

docs: Add MCP Section (#2777)

Sarthak Bhardwaj16e90dbdcb02
diff --git a/docs/mintlify/docs.json b/docs/mintlify/docs.json
index 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.png
new file mode 100644
index 000000000..884f754bd
Binary files /dev/null and b/docs/mintlify/images/camel_toolks_as_mcp_server.png differ
diff --git a/docs/mintlify/images/claude_example1.png b/docs/mintlify/images/claude_example1.png
new file mode 100644
index 000000000..0194f0a3e
Binary files /dev/null and b/docs/mintlify/images/claude_example1.png differ
diff --git a/docs/mintlify/images/claude_example2.png b/docs/mintlify/images/claude_example2.png
new file mode 100644
index 000000000..5ac3a0994
Binary files /dev/null and b/docs/mintlify/images/claude_example2.png differ
diff --git a/docs/mintlify/images/mcp-architecture.jpeg b/docs/mintlify/images/mcp-architecture.jpeg
new file mode 100644
index 000000000..17fde6194
Binary files /dev/null and b/docs/mintlify/images/mcp-architecture.jpeg differ
diff --git a/docs/mintlify/images/mcp-client-server-example.png b/docs/mintlify/images/mcp-client-server-example.png
new file mode 100644
index 000000000..8b1152826
Binary files /dev/null and b/docs/mintlify/images/mcp-client-server-example.png differ
diff --git a/docs/mintlify/images/mcp-without-vs-with.jpg b/docs/mintlify/images/mcp-without-vs-with.jpg
new file mode 100644
index 000000000..29b656996
Binary files /dev/null and b/docs/mintlify/images/mcp-without-vs-with.jpg differ
diff --git a/docs/mintlify/mcp/camel_agents_as_an_mcp_clients.mdx b/docs/mintlify/mcp/camel_agents_as_an_mcp_clients.mdx
new file mode 100644
index 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.mdx
new file mode 100644
index 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.mdx
new file mode 100644
index 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.mdx
new file mode 100644
index 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 file
diff --git a/docs/mintlify/mcp/overview.mdx b/docs/mintlify/mcp/overview.mdx
new file mode 100644
index 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.
+
+![MCP Server/Client diagram](/images/mcp-client-server-example.png)
+### 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.
+
+---
+