You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
- [Signaling and Human input](#signaling-and-human-input)
337
-
- [App Config](#app-config)
338
-
- [MCP Server Management](#mcp-server-management)
339
-
- [Contributing](#contributing)
340
-
- [Roadmap](#roadmap)
341
-
- [FAQs](#faqs)
342
-
343
317
## Why use `mcp-agent`?
344
318
345
319
There are too many AI frameworks out there already. But `mcp-agent` is the only one that is purpose-built for a shared protocol - [MCP](https://modelcontextprotocol.io/introduction). It is also the most lightweight, and is closer to an agent pattern library than a framework.
346
320
347
321
As [more services become MCP-aware](https://github.com/punkpeye/awesome-mcp-servers), you can use mcp-agent to build robust and controllable AI agents that can leverage those services out-of-the-box.
348
322
349
-
## Examples
350
-
351
-
Before we go into the core concepts of mcp-agent, let's show what you can build with it.
352
-
353
-
In short, you can build any kind of AI application with mcp-agent: multi-agent collaborative workflows, human-in-the-loop workflows, RAG pipelines and more.
354
-
355
-
### Claude Desktop
356
-
357
-
You can integrate mcp-agent apps into MCP clients like Claude Desktop.
358
-
359
-
#### mcp-agent server
360
-
361
-
This app wraps an mcp-agent application inside an MCP server, and exposes that server to Claude Desktop.
362
-
The app exposes agents and workflows that Claude Desktop can invoke to service of the user's request.
**Link to code**: [examples/usecases/marimo_mcp_basic_agent](./examples/usecases/marimo_mcp_basic_agent/)
417
-
418
-
> [!NOTE]
419
-
> Huge thanks to [Akshay Agrawal (@akshayka)](https://github.com/akshayka)
420
-
>for developing and contributing this example!
421
-
422
-
### Python
327
+
```bash
328
+
uv run mcp-agent login
329
+
uv run mcp-agent deploy my-agent
330
+
```
423
331
424
-
You can write mcp-agent apps as Python scripts or Jupyter notebooks.
332
+
The CLI packages your project, uploads secrets, and returns an MCP endpoint (HTTP/SSE) plus workflow operations you can resume via `uv run mcp-agent workflows`.
425
333
426
-
#### Swarm
334
+
Docs: [Cloud overview](https://docs.mcp-agent.com/cloud/overview) • [Deploy to Cloud guide](https://docs.mcp-agent.com/get-started/deploy-to-cloud)
427
335
428
-
This example demonstrates a multi-agent setup forhandling different customer service requestsin an airline context using the Swarm workflow pattern. The agents can triage requests, handle flight modifications, cancellations, and lost baggage cases.
Explore the [Example Gallery](docs/examples/README.md) for runnable demos across Claude Desktop, Streamlit, Marimo, Temporal workflows, and more. Highlights:
431
339
432
-
**Link to code**: [examples/workflows/workflow_swarm](./examples/workflows/workflow_swarm/)
340
+
- **Claude Desktop – Agent server**. Wraps an mcp-agent app in an MCP server so Claude can orchestrate multi-agent grading. [Video](https://github.com/user-attachments/assets/7807cffd-dba7-4f0c-9c70-9482fd7e0699) · [Code](./examples/basic/mcp_server_aggregator) · Thanks [@StreetLamb](https://github.com/StreetLamb).
341
+
- **Streamlit Gmail agent**. Read/send mail via the Gmail MCP server with a Streamlit UI. [Video](https://github.com/user-attachments/assets/54899cac-de24-4102-bd7e-4f0c-9c70-9482fd7e0699) · [Code](https://github.com/jasonsum/gmail-mcp-server/blob/add-mcp-agent-streamlit/streamlit_app.py) · Thanks [@jasonsum](https://github.com/jasonsum).
342
+
- **Streamlit RAG chatbot**. Q&A over a corpus using Qdrant through MCP. [Video](https://github.com/user-attachments/assets/f4dcd227-cae9-4a59-aa9e-0eceeb4acaf4) · [Code](./examples/usecases/streamlit_mcp_rag_agent) · Thanks [@StreetLamb](https://github.com/StreetLamb).
343
+
- **Marimo notebook agent**. Reactive notebook front-end for the finder agent. <img src="https://github.com/user-attachments/assets/139a95a5-e3ac-4ea7-9c8f-bad6577e8597" width="320"/> · [Code](./examples/usecases/marimo_mcp_basic_agent) · Thanks [@akshayka](https://github.com/akshayka).
344
+
- **Python Swarm CLI**. Airline support workflow using the Swarm pattern. [Video](https://github.com/user-attachments/assets/b314d75d-7945-4de6-965b-7f21eb14a8bd) · [Code](./examples/workflows/workflow_swarm).
433
345
434
346
## Core Components
435
347
@@ -447,6 +359,16 @@ Everything in the framework is a derivative of these core capabilities.
447
359
mcp-agent provides implementations forevery patternin Anthropic’s [Building Effective Agents](https://www.anthropic.com/research/building-effective-agents), as well as the OpenAI [Swarm](https://github.com/openai/swarm) pattern.
448
360
Each pattern is model-agnostic, and exposed as an `AugmentedLLM`, making everything very composable.
| Router |`create_router_llm(...)` / `create_router_embedding(...)`| Route requests to the best agent, server, or function.<br><img src="https://www.anthropic.com/_next/image?url=https%3A%2F%2Fwww-cdn.anthropic.com%2Fimages%2F4zrzovbb%2Fwebsite%2F5c0c0e9fe4def0b584c04d37849941da55e5e71c-2401x1000.png&w=3840&q=75" width="260"/>| [Router](https://docs.mcp-agent.com/mcp-agent-sdk/effective-patterns/router) |
366
+
| Intent classifier |`create_intent_classifier_llm(...)` / `create_intent_classifier_embedding(...)`| Bucket user input into intents before automation. | [Intent classifier](https://docs.mcp-agent.com/mcp-agent-sdk/effective-patterns/intent-classifier) |
| Deep research |`create_deep_orchestrator(...)`| Long-horizon research with knowledge extraction and policy checks. | [Deep research](https://docs.mcp-agent.com/mcp-agent-sdk/effective-patterns/deep-research) |
369
+
| Evaluator-optimizer |`create_evaluator_optimizer_llm(...)`| Iterate until an evaluator approves the result.<br><img src="https://www.anthropic.com/_next/image?url=https%3A%2F%2Fwww-cdn.anthropic.com%2Fimages%2F4zrzovbb%2Fwebsite%2F14f51e6406ccb29e695da48b17017e899a6119c7-2401x1000.png&w=3840&q=75" width="260"/>| [Evaluator-optimizer](https://docs.mcp-agent.com/mcp-agent-sdk/effective-patterns/evaluator-optimizer) |
[AugmentedLLM](./src/mcp_agent/workflows/llm/augmented_llm.py) is an LLM that has access to MCP servers and functions via Agents.
@@ -662,8 +584,107 @@ print("Result:", result)
662
584
663
585
</details>
664
586
587
+
## Durable execution
588
+
589
+
Switch `execution_engine` to `temporal` when you want long-running workflows with retries, pause/resume, and audit history. The workflow code stays the same—mcp-agent handles Temporal activities and signals for you.
590
+
591
+
```python
592
+
from mcp_agent.app import MCPApp
593
+
from mcp_agent.config import Settings
594
+
from mcp_agent.executor.workflow import Workflow, WorkflowResult
Run a Temporal worker with `uv run mcp-agent workflows run ...` or see [`examples/temporal`](./examples/temporal) for a full setup with resume commands.
Expose any MCPApp as an MCP server so Claude, Cursor, VS Code, or other agents can call your workflows.
613
+
614
+
```python
615
+
from mcp_agent.server.app_server import create_mcp_server_for_app
616
+
617
+
async def main():
618
+
async with app.run() as running_app:
619
+
server = create_mcp_server_for_app(running_app)
620
+
await server.run_stdio_async()
621
+
```
622
+
623
+
The server automatically exports decorated tools (`@app.tool`, `@app.async_tool`) plus management endpoints such as `workflows-list` and `workflows-get_status`.
624
+
625
+
Docs: [Agent as MCP server](https://docs.mcp-agent.com/mcp-agent-sdk/mcp/agent-as-mcp-server)
626
+
627
+
## CLI reference
628
+
629
+
```bash
630
+
uvx mcp-agent --help
631
+
```
632
+
633
+
- `uvx mcp-agent init` – scaffold a project.
634
+
- `uvx mcp-agent deploy` – deploy to mcp-agent Cloud.
Create an [`mcp_agent.config.yaml`](/schema/mcp-agent.config.schema.json) and define secrets via either a gitignored [`mcp_agent.secrets.yaml`](./examples/basic/mcp_basic_agent/mcp_agent.secrets.yaml.example) or a local [`.env`](./examples/basic/mcp_basic_agent/.env.example). In production, prefer `MCP_APP_SETTINGS_PRELOAD` to avoid writing plaintext secrets to disk.
768
814
769
815
### MCP server management
@@ -875,6 +921,12 @@ There have already been incredible community contributors who are driving this p
875
921
- [Jerron Lim (@StreetLamb)](https://github.com/StreetLamb) -- who has contributed countless hours and excellent examples, and great ideas to the project.
876
922
- [Jason Summer (@jasonsum)](https://github.com/jasonsum) -- for identifying several issues and adapting his Gmail MCP server to work with mcp-agent
We will be adding a detailed roadmap (ideally driven by your feedback). The current set of priorities include:
@@ -920,6 +972,14 @@ You can embed mcp-agent in an MCP client directly to manage the orchestration ac
920
972
921
973
You can use mcp-agent applications in a standalone fashion (i.e. they aren't part of an MCP client). The [`examples`](/examples/) are all standalone applications.
922
974
975
+
### How do I deploy to Cloud?
976
+
977
+
Run `uvx mcp-agent deploy <app-name>` after logging in with `uvx mcp-agent login`. The CLI packages your project, provisions secrets, and exposes an MCP endpoint backed by a durable Temporal runtime. See the [Cloud quickstart](https://docs.mcp-agent.com/get-started/deploy-to-cloud) for step-by-step screenshots and CLI output.
978
+
979
+
### Where is the API reference?
980
+
981
+
Every class, decorator, and CLI command is documented on [docs.mcp-agent.com](https://docs.mcp-agent.com). The [API reference](https://docs.mcp-agent.com/reference) and the [`llms-full.txt`](https://docs.mcp-agent.com/llms-full.txt) are designed so LLMs (or you) can ingest the whole surface area easily.
982
+
923
983
### Tell me a fun fact
924
984
925
985
I debated naming this project _silsila_ (سلسلہ), which means chain of events in Urdu. mcp-agent is more matter-of-fact, but there's still an easter egg in the project paying homage to silsila.
0 commit comments