---
title: MCP Server
subtitle: Connect AI assistants to browser automation via Model Context Protocol
slug: going-to-production/mcp
---
{/* This file (docs/) and fern/integrations/mcp.mdx must stay in sync. docs/ is for Mintlify, fern/ is for Fern. Minor formatting differences (Tip vs inline text, CardGroup) are OK since the platforms support different components. */}

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.

## What you can do

The MCP server exposes 33 tools across 6 categories:

| Category | Key tools | What they do |
|----------|-----------|--------------|
| **Browser session management** | `skyvern_browser_session_create`, `skyvern_browser_session_close`, `skyvern_browser_session_list`, `skyvern_browser_session_connect` | Open, manage, and reuse browser sessions |
| **Browser actions** | `skyvern_act`, `skyvern_navigate`, `skyvern_click`, `skyvern_type`, `skyvern_scroll`, `skyvern_select_option`, `skyvern_press_key`, `skyvern_wait` | Control the browser with natural language or CSS/XPath selectors |
| **Data extraction** | `skyvern_extract`, `skyvern_screenshot`, `skyvern_evaluate` | Pull structured data from pages, capture screenshots, run JavaScript |
| **Validation** | `skyvern_validate` | Check page conditions using AI (returns true/false) |
| **Credentials** | `skyvern_credential_list`, `skyvern_credential_get`, `skyvern_credential_delete` | Look up stored credentials for login flows |
| **Workflows** | `skyvern_workflow_create`, `skyvern_workflow_run`, `skyvern_workflow_status`, `skyvern_workflow_get`, `skyvern_workflow_update`, `skyvern_workflow_delete` | Build and execute multi-step automations |

Your AI assistant decides which tools to call based on your instructions. For example, asking "go to Hacker News and get the top post title" triggers `skyvern_browser_session_create`, `skyvern_navigate`, `skyvern_extract`, and `skyvern_browser_session_close` automatically.

## Which setup should I use?

| | Cloud setup (recommended) | Local mode |
|---|---|---|
| **Best for** | Most users — Skyvern Cloud handles everything | Self-hosting Skyvern with your own infrastructure |
| **Install required** | None | Python 3.11+ and `pip install skyvern` |
| **How it connects** | Your AI client connects to Skyvern Cloud over HTTPS | A local Python process runs on your machine |
| **API key** | From [app.skyvern.com](https://app.skyvern.com) | From your self-hosted Skyvern instance |

If you have a Skyvern Cloud account, use the cloud setup below. It takes 30 seconds and works immediately.

## Quick start

Get your API key from [Settings](https://app.skyvern.com) in the Skyvern dashboard, then pick your client below.

<Tabs>
<Tab title="Claude Code">

```bash
claude mcp add-json skyvern '{"type":"http","url":"https://api.skyvern.com/mcp/","headers":{"x-api-key":"YOUR_SKYVERN_API_KEY"}}' --scope user
```

</Tab>
<Tab title="Claude Desktop">

Add to your Claude Desktop config file (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `~/.config/Claude/claude_desktop_config.json` on Linux):

```json
{
  "mcpServers": {
    "Skyvern": {
      "type": "streamable-http",
      "url": "https://api.skyvern.com/mcp/",
      "headers": {
        "x-api-key": "YOUR_SKYVERN_API_KEY"
      }
    }
  }
}
```

</Tab>
<Tab title="Cursor">

Add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "Skyvern": {
      "type": "streamable-http",
      "url": "https://api.skyvern.com/mcp/",
      "headers": {
        "x-api-key": "YOUR_SKYVERN_API_KEY"
      }
    }
  }
}
```

</Tab>
<Tab title="Windsurf">

Add to `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "Skyvern": {
      "type": "streamable-http",
      "url": "https://api.skyvern.com/mcp/",
      "headers": {
        "x-api-key": "YOUR_SKYVERN_API_KEY"
      }
    }
  }
}
```

</Tab>
<Tab title="Codex">

Add to `~/.codex/config.toml`:

```toml
[mcp_servers.skyvern]
url = "https://api.skyvern.com/mcp/"

[mcp_servers.skyvern.http_headers]
x-api-key = "YOUR_SKYVERN_API_KEY"
```

To load the API key from an environment variable instead, use `env_http_headers`:

```toml
[mcp_servers.skyvern.env_http_headers]
x-api-key = "SKYVERN_API_KEY"
```

</Tab>
</Tabs>

That's it — no Python, no `pip install`, no local server. Your AI assistant connects directly to Skyvern Cloud over HTTPS.

## Alternative: Local mode (self-hosted)

Use this if you are self-hosting Skyvern and want the MCP server to talk to your own instance instead of Skyvern Cloud. This runs a lightweight Python process on your machine that connects to your local Skyvern server. Requires Python 3.11, 3.12, or 3.13.

```bash
pip install skyvern
```

Before using MCP, start your local Skyvern server:

```bash
skyvern run server
```

Then configure your AI client to use stdio transport:

<Tabs>
<Tab title="Claude Code">

```bash
# For Skyvern Cloud, use https://api.skyvern.com instead of localhost
claude mcp add --transport stdio skyvern \
  --env SKYVERN_BASE_URL=http://localhost:8000 \
  --env SKYVERN_API_KEY=YOUR_SKYVERN_API_KEY \
  -- python3 -m skyvern run mcp
```

</Tab>
<Tab title="Claude Desktop / Cursor / Windsurf">

Add to your client's config file:

```json
{
  "mcpServers": {
    "Skyvern": {
      "command": "/usr/bin/python3",
      "args": ["-m", "skyvern", "run", "mcp"],
      "env": {
        "SKYVERN_BASE_URL": "http://localhost:8000",
        "SKYVERN_API_KEY": "YOUR_SKYVERN_API_KEY"
      }
    }
  }
}
```

Replace `/usr/bin/python3` with the output of `which python3`. For Skyvern Cloud, change `SKYVERN_BASE_URL` to `https://api.skyvern.com`.

</Tab>
<Tab title="Codex">

```toml
[mcp_servers.skyvern]
command = "/usr/bin/python3"
args = ["-m", "skyvern", "run", "mcp"]

[mcp_servers.skyvern.env]
SKYVERN_BASE_URL = "http://localhost:8000"
SKYVERN_API_KEY = "YOUR_SKYVERN_API_KEY"
```

Replace `/usr/bin/python3` with the output of `which python3`. For Skyvern Cloud, change `SKYVERN_BASE_URL` to `https://api.skyvern.com`.

</Tab>
</Tabs>

<Tip>
You can also run `skyvern init` to auto-detect installed clients and write configs automatically.
</Tip>

<Accordion title="Config file locations by client">

| 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>

## See it in action

**Claude Desktop** looking up the top Hacker News posts:

<video style={{ aspectRatio: '16 / 9', width: '100%' }} controls>
  <source src="https://github.com/user-attachments/assets/0c10dd96-c6ff-4b99-ad99-f34a5afd04fe" type="video/mp4" />
</video>

**Cursor** finding programming jobs:

<video style={{ aspectRatio: '16 / 9', width: '100%' }} controls>
  <source src="https://github.com/user-attachments/assets/084c89c9-6229-4bac-adc9-6ad69b41327d" type="video/mp4" />
</video>

**Windsurf** searching Form 5500 and downloading files:

<video style={{ aspectRatio: '16 / 9', width: '100%' }} controls>
  <source src="https://github.com/user-attachments/assets/70cfe310-24dc-431a-adde-e72691f198a7" type="video/mp4" />
</video>

## Troubleshooting

<Accordion title="Invalid API key or 401 errors">
Double-check that your API key is correct. You can find or regenerate it at [Settings](https://app.skyvern.com). Make sure there are no extra spaces or newlines when pasting the key.

If you recently regenerated your API key, update it in your MCP config and restart your AI client.
</Accordion>

<Accordion title="Tools not responding or timing out">
Skyvern browser sessions take a few seconds to start. If a tool call times out, try again — the first call in a new session is slower than subsequent ones.

If timeouts persist, check that your Skyvern account is active and has available credits at [app.skyvern.com](https://app.skyvern.com).
</Accordion>

<Accordion title="Python version errors (local mode only)">
The Skyvern MCP server requires Python 3.11, 3.12, or 3.13. Check your version with `python3 --version`. If you have multiple Python versions installed, make sure the `command` in your MCP config points to a supported version:

```bash
which python3.11
# Use this path in your MCP config
```

You can also use `pipx` to install in an isolated environment:

```bash
pipx install skyvern
```
</Accordion>

<Accordion title="Connection refused (local mode)">
Make sure the Skyvern server is running before using MCP tools:

```bash
skyvern run server
```

Confirm the server is reachable at `http://localhost:8000`. If you changed the port, update `SKYVERN_BASE_URL` in your MCP config to match.
</Accordion>

<Accordion title="MCP client doesn't detect Skyvern">
Verify that the `command` path in your MCP config is correct:

```bash
which python3
```

Use the full absolute path (e.g., `/usr/bin/python3` or `/Users/you/.pyenv/shims/python3`), not just `python3`. Restart your MCP client after editing the config file.
</Accordion>

