docs(examples): add multi-server + agent integration guides

examples/README.md

@@ -0,0 +1,49 @@
+# mcp-forge examples
+
+Two scenarios, two folders. Pick the one that matches what you want to do.
+
+## Mental model
+
+`mcp-forge` is a **server-side framework**. It scaffolds and runs MCP servers — it
+does **not** give you an agent. Your agent is a separate process that connects
+to the server(s) over a transport (HTTP or stdio).
+
+```
+┌────────────┐     HTTP (default)      ┌────────────────┐     ┌─────────────┐
+│   Agent    │ ─────────────────────▶  │  MCP server    │ ──▶ │  Providers  │
+│  (you own) │   or stdio (desktop)    │  (mcp-forge)   │     │ (InMemory / │
+│            │                         │  = FastMCP     │     │  AWS / ...) │
+└────────────┘                         └────────────────┘     └─────────────┘
+```
+
+- `create_mcp_app()` returns a `FastMCP` instance and `run_server()` starts it.
+  HTTP is default; set `MCP_SERVER_MODE=stdio` for Claude Desktop and similar.
+  See [`packages/mcp-forge-core/src/mcp_forge_core/server_factory.py`](../packages/mcp-forge-core/src/mcp_forge_core/server_factory.py).
+- The CLI (`mcp-forge new <name>-mcp`) scaffolds a working server from templates.
+  See [`packages/mcp-forge-cli`](../packages/mcp-forge-cli).
+
+## Which example?
+
+| Folder | When to use |
+|--------|-------------|
+| [`multi-server/`](./multi-server/) | You just need several MCP servers running locally (or in containers). No agent yet. |
+| [`agent-integration/`](./agent-integration/) | You already have (or want to build) an agent that talks to those servers. |
+
+Most users do both: start with `multi-server/` to get servers up, then move to
+`agent-integration/` to wire them into their agent.
+
+## Prerequisites
+
+- Python 3.11+
+- `pip install mcp-forge-cli` (pulls in `mcp-forge-core`)
+- Docker (optional — only needed for the `docker-compose.yml` in `multi-server/`)
+- AWS credentials (optional — only if you swap in the DynamoDB / CloudWatch / Bedrock providers)
+
+## Notes on the code you'll see
+
+- **Server-side** code (scaffolded projects, provider wiring, tool functions)
+  is real and runs. Every command can be executed verbatim.
+- **Agent-side** code (`agent.py` in `anthropic-sdk/` and `langchain-langgraph/`)
+  is **pseudo-code**: the import paths and APIs of the `mcp` client library and
+  agent frameworks move fast. Use these files as a blueprint, then adjust to
+  the versions you install.

examples/agent-integration/README.md

@@ -0,0 +1,50 @@
+# Scenario B — Connect your agent to the servers
+
+You have servers (the three from [`../multi-server/`](../multi-server/)) running
+on `localhost:8001`, `:8002`, `:8003`. Now drive them from an agent you own.
+
+## Transport choice
+
+`mcp-forge` servers support two transports, chosen via the `MCP_SERVER_MODE`
+env var on the **server** side:
+
+| Mode | When | How the client connects |
+|---|---|---|
+| `http` (default) | Production, containers, anywhere the agent is a separate process. | HTTP POST / streamable-HTTP to `http://host:port/mcp` |
+| `stdio` | Claude Desktop, local dev, subprocess-style embedding. | Client spawns the server as a subprocess and talks over stdin/stdout. |
+
+The rest of this folder assumes **HTTP** (it's the default and what
+`docker-compose up` in `../multi-server/` uses). If you need stdio, see
+[stdio note](#stdio-note) at the bottom.
+
+## Pick your framework
+
+| Folder | Best for |
+|---|---|
+| [`anthropic-sdk/`](./anthropic-sdk/) | You want a minimal, explicit agent loop with the official `anthropic` SDK + `mcp` Python client. Maximum control, smallest dependency set. |
+| [`langchain-langgraph/`](./langchain-langgraph/) | You already use LangChain/LangGraph, or you want a pre-built ReAct agent with conditional edges, memory, etc. |
+
+Both folders connect to the same three servers. You can copy whichever one
+matches your stack.
+
+## Prerequisites (both options)
+
+1. Servers running — `cd ../multi-server && docker-compose up` (or the three
+   terminals approach).
+2. `ANTHROPIC_API_KEY` exported (both examples drive Claude).
+3. Python 3.11+.
+
+## Pseudo-code warning
+
+The `agent.py` in each sub-folder is **pseudo-code**. The MCP Python client
+library and the LangChain-MCP adapters are under active development — their
+exact import paths and method signatures change between releases. Use the
+files as a blueprint, then pin versions and adapt imports to what `pip`
+actually installs for you.
+
+## <a id="stdio-note"></a>stdio note
+
+If you point the server at stdio (`MCP_SERVER_MODE=stdio python -m search_mcp.server`),
+replace `streamablehttp_client(url)` with `stdio_client(server_params)` on the
+client side (the `mcp` package provides both). The rest of the agent code
+doesn't change.