Automate browser based workflows with AI
Python aiapiautomationbrowserbrowser-automationcomputergptllmplaywrightpowerautomatepuppeteerpythonrpaseleniumvisionworkflow
Mount MCP remote server on existing API service at /mcp (#4843)
Marc Kelechava96343ab525ad
diff --git a/docs/integrations/mcp.mdx b/docs/integrations/mcp.mdxindex 87485813f..62231790c 100644--- a/docs/integrations/mcp.mdx+++ b/docs/integrations/mcp.mdx@@ -4,10 +4,10 @@ subtitle: Connect AI assistants to browser automation via Model Context Protocolslug: going-to-production/mcp----The Skyvern MCP server lets AI assistants like Claude Desktop, Cursor, and Windsurf control a browser. Your AI can fill out forms, extract data, download files, and run multi-step workflows, all through natural language.+The Skyvern MCP server lets AI assistants like Claude Desktop, Claude Code, Codex, Cursor, and Windsurf control a browser. Your AI can fill out forms, extract data, download files, and run multi-step workflows, all through natural language.<Note>-Requires Python 3.11, 3.12, or 3.13.+Local (stdio) mode requires Python 3.11, 3.12, or 3.13. Remote HTTP mode has no local dependencies.</Note>## What you can do@@ -47,9 +47,13 @@ skyvern run server```</Tip>-### Option B: Manual configuration+### Option B: Manual configuration (stdio — runs locally)-Add this to your MCP client's configuration file:+Each client has its own config file and format. Pick your client below.++<Accordion title="Claude Desktop / Cursor / Windsurf (JSON)">++Add to your client's config file (see config file locations table below):```json{@@ -66,24 +70,70 @@ Add this to your MCP client's configuration file:}```-Replace `/usr/bin/python3` with the output of `which python3` on your machine. For local mode, set `SKYVERN_BASE_URL` to `http://localhost:8000` and find your API key in the `.env` file after running `skyvern init`.+Replace `/usr/bin/python3` with the output of `which python3` on your machine. For local mode, set `SKYVERN_BASE_URL` to `http://localhost:8000`.++</Accordion>++<Accordion title="Claude Code (JSON)">++Add to `.mcp.json` in your project root (version-controlled), or `~/.claude.json` for global config:++```json+{+ "mcpServers": {+ "skyvern": {+ "type": "stdio",+ "command": "/usr/bin/python3",+ "args": ["-m", "skyvern", "run", "mcp"],+ "env": {+ "SKYVERN_BASE_URL": "https://api.skyvern.com",+ "SKYVERN_API_KEY": "YOUR_SKYVERN_API_KEY"+ }+ }+ }+}+```++Replace `/usr/bin/python3` with the output of `which python3`.++</Accordion>++<Accordion title="Codex (TOML)">++Add to `~/.codex/config.toml` (global) or `.codex/config.toml` in a trusted project:++```toml+[mcp_servers.skyvern]+command = "/usr/bin/python3"+args = ["-m", "skyvern", "run", "mcp"]++[mcp_servers.skyvern.env]+SKYVERN_BASE_URL = "https://api.skyvern.com"+SKYVERN_API_KEY = "YOUR_SKYVERN_API_KEY"+```++Replace `/usr/bin/python3` with the output of `which python3`. You can also run `codex mcp add skyvern -- python3 -m skyvern run mcp` to add it interactively.++</Accordion>-### Option C: Remote MCP over HTTPS (streamable HTTP)+### Option C: Remote MCP over HTTPS (streamable HTTP) — recommended for cloud users-Use this when your team provides a hosted MCP endpoint (for example: `https://mcp.skyvern.com/mcp`).+Connect directly to Skyvern's hosted MCP endpoint. No local Python installation required.In remote HTTP mode:- Clients must send `x-api-key` on every request.- Use `skyvern_session_create` first, then pass `session_id` explicitly on subsequent browser tool calls.-If your MCP client supports native remote HTTP transport, configure it directly:+If your MCP client supports native remote HTTP transport, configure it directly.++<Accordion title="Claude Desktop / Cursor / Windsurf / Claude Code (JSON)">```json{"mcpServers": {- "SkyvernRemote": {+ "Skyvern": {"type": "streamable-http",- "url": "https://mcp.skyvern.com/mcp",+ "url": "https://api.skyvern.com/mcp","headers": {"x-api-key": "YOUR_SKYVERN_API_KEY"}@@ -92,14 +142,49 @@ If your MCP client supports native remote HTTP transport, configure it directly:}```+For Claude Code, add to `.mcp.json` in your project root or `~/.claude.json` globally.++</Accordion>++<Accordion title="Codex (TOML)">++```toml+[mcp_servers.skyvern]+url = "https://api.skyvern.com/mcp"++[mcp_servers.skyvern.env_http_headers]+x-api-key = "SKYVERN_API_KEY"+```++Set the `SKYVERN_API_KEY` environment variable, or use `http_headers` for a static value:++```toml+[mcp_servers.skyvern]+url = "https://api.skyvern.com/mcp"++[mcp_servers.skyvern.http_headers]+x-api-key = "YOUR_SKYVERN_API_KEY"+```++</Accordion>++<Tip>+This is the simplest setup for Skyvern Cloud users — no Python, no `pip install`, just paste the config and go.+Get your API key from [Settings](https://app.skyvern.com) in the Skyvern dashboard.+</Tip>+<Accordion title="Config file locations by client">-| Client | Path |-|--------|------|-| **Claude Desktop** (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |-| **Claude Desktop** (Linux) | `~/.config/Claude/claude_desktop_config.json` |-| **Cursor** | `~/.cursor/mcp.json` |-| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` |+| Client | Format | Path |+|--------|--------|------|+| **Claude Desktop** (macOS) | JSON | `~/Library/Application Support/Claude/claude_desktop_config.json` |+| **Claude Desktop** (Linux) | JSON | `~/.config/Claude/claude_desktop_config.json` |+| **Claude Code** (project) | JSON | `.mcp.json` in project root |+| **Claude Code** (global) | JSON | `~/.claude.json` |+| **Codex** (global) | TOML | `~/.codex/config.toml` |+| **Codex** (project) | TOML | `.codex/config.toml` in trusted project |+| **Cursor** | JSON | `~/.cursor/mcp.json` |+| **Windsurf** | JSON | `~/.codeium/windsurf/mcp_config.json` |</Accordion>diff --git a/skyvern/cli/setup_commands.py b/skyvern/cli/setup_commands.pyindex 693b0e1d0..15a70b8ef 100644--- a/skyvern/cli/setup_commands.py+++ b/skyvern/cli/setup_commands.py@@ -22,7 +22,7 @@ from skyvern.utils.env_paths import resolve_backend_env_path# migrated to use _upsert_mcp_config() in a follow-up.setup_app = typer.Typer(help="Register Skyvern MCP with AI coding tools.")-_DEFAULT_REMOTE_URL = "https://mcp.skyvern.com/mcp"+_DEFAULT_REMOTE_URL = "https://api.skyvern.com/mcp"# ---------------------------------------------------------------------------@@ -207,7 +207,7 @@ _local_opt = typer.Option(False, "--local", help="Use local stdio transport inst_python_path_opt = typer.Option(False, "--use-python-path", help="(local only) Use python -m skyvern instead of skyvern entrypoint")-_url_opt = typer.Option(None, "--url", help="Remote MCP endpoint URL (default: https://mcp.skyvern.com/mcp)")+_url_opt = typer.Option(None, "--url", help="Remote MCP endpoint URL (default: https://api.skyvern.com/mcp)")# ---------------------------------------------------------------------------diff --git a/skyvern/forge/api_app.py b/skyvern/forge/api_app.pyindex 46c4ad43a..dad56250b 100644--- a/skyvern/forge/api_app.py+++ b/skyvern/forge/api_app.py@@ -75,7 +75,18 @@ async def lifespan(fastapi_app: FastAPI) -> AsyncGenerator[None, Any]:if cleanup_task:LOG.info("Cleanup scheduler started")- yield+ # Start MCP sub-application lifespan if mounted. Starlette Mount does NOT+ # forward lifespan events to sub-apps, so we must enter the MCP app's+ # lifespan here. This initializes the streamable-http session manager's+ # task group which is required for handling MCP requests.+ mcp_app = getattr(fastapi_app.state, "mcp_starlette_app", None)+ if mcp_app:+ async with mcp_app.lifespan(mcp_app):+ LOG.info("MCP remote server lifespan started")+ yield+ LOG.info("MCP remote server lifespan stopped")+ else:+ yield# Stop cleanup schedulerawait stop_cleanup_scheduler()