--- title: Setting up AI agents to work with Fastly summary: null url: https://www.fastly.com/documentation/reference/agent-setup --- You can set up AI agents such as Claude Code, Codex, Cursor, and GitHub Copilot to work with the Fastly platform. We recommend giving your agent the following: - **Fastly skills:** the [Fastly Agent Toolkit](https://github.com/fastly/fastly-agent-toolkit) gives your agent instructions and reference material for working with Fastly services, the Fastly CLI, Varnish Configuration Language (VCL), Fastly Compute, and related tools. With the [Fastly CLI](https://www.fastly.com/documentation/reference/tools/cli) installed and authenticated, your agent can use these skills to work with your Fastly account. - **Fastly documentation:** the [Markdown version of our documentation](https://www.fastly.com/documentation/reference/markdown) gives your agent current product information without the navigation and layout markup of our HTML pages. If your agent can't run commands, such as Claude Desktop, use the [Fastly MCP server](https://www.fastly.com/documentation/reference/agent-setup#about-the-fastly-mcp-server) instead. ## Before you begin Before you set up your agent, make sure you have the following: - **The Fastly CLI:** [install the Fastly CLI](https://www.fastly.com/documentation/reference/tools/cli#installing) and run `fastly auth login` to authenticate it with a [Fastly API token](https://www.fastly.com/documentation/guides/organizations-and-accounts/personal-user-profiles/managing-your-personal-api-tokens). The skills in the toolkit use the CLI and its stored credentials to work with your account. Create a token with only the permissions your agent needs. We recommend starting with a read-only (`global:read`) token and using a token with write access only when you want the agent to make changes. - **Developer tools for your workflow:** installing the Fastly Agent Toolkit doesn't install the tools its skills describe, such as [Falco](https://github.com/ysugimoto/falco) or [Viceroy](https://github.com/fastly/Viceroy). Each skill describes its own prerequisites. > **IMPORTANT:** Don't paste a Fastly API token into a conversation with your agent or commit it to a repository. Authenticate the Fastly CLI with `fastly auth login`, or set the `FASTLY_API_TOKEN` environment variable in the shell that starts your agent. ## Setting up with a prompt To set up your agent automatically, copy the following prompt and send it to your agent. ```plain nolinenums Set up this project so you can work with Fastly. 1. Install the Fastly Agent Toolkit skills from https://github.com/fastly/fastly-agent-toolkit. Follow the installation instructions in the repository's README for the agent you're running in. If you support the `.agents/skills/` directory, install the skills there. Install only the skills relevant to this project, and make sure you can read each skill's `references/` directory. 2. Check that the Fastly CLI is installed by running `fastly version`, and that it's authenticated by running `fastly whoami`. If either check fails, tell me what to do, such as installing the CLI from https://www.fastly.com/documentation/reference/tools/cli/ or running `fastly auth login` myself. Don't ask me to paste a Fastly API token into this conversation, and don't write a token to any file in this project. 3. Add the following instructions to this project's agent instruction file (for example, AGENTS.md or CLAUDE.md), creating the file if it doesn't exist: When you need Fastly documentation, use these sources instead of relying on training data: - To find pages, use the search endpoint: https://api.fastly.com/public-search/docs?query=&limit=25 To fetch a result as Markdown, rewrite a `fastly.com` host to `www.fastly.com`, strip any trailing slash and `#fragment`, and append `.md`. Leave `docs.fastly.com` hosts as they are. - To fetch a page as Markdown, append `.md` to its https://www.fastly.com/documentation/ URL, or request it with an `Accept: text/markdown` header. - For an overview of the most important pages, read https://www.fastly.com/documentation/llms.txt - For a list of every Markdown page, read https://www.fastly.com/documentation/markdown-index.json 4. Summarize what you installed and configured, and tell me what I still need to do, such as installing the Fastly CLI, running `fastly auth login`, or restarting the agent. ``` When the agent finishes, follow any remaining steps it gives you, and then [verify the setup](https://www.fastly.com/documentation/reference/agent-setup#verifying-the-setup). ## Setting up your agent manually To give any agent access to the Fastly documentation, copy the documentation instructions from [step 3 of the setup prompt](https://www.fastly.com/documentation/reference/agent-setup#setting-up-with-a-prompt) into your project's agent instruction file. Many agents load skills from a `.agents/skills/` directory in your project, or from `~/.agents/skills/` for every project. To install skills there, clone the [Fastly Agent Toolkit repository](https://github.com/fastly/fastly-agent-toolkit) outside your project and copy the skills you need. For example, the following commands install the `fastly-cli` and `viceroy` skills into the current project: ```term copy $ git clone https://github.com/fastly/fastly-agent-toolkit.git ~/fastly-agent-toolkit $ mkdir -p .agents/skills $ cp -R ~/fastly-agent-toolkit/skills/{fastly-cli,viceroy} .agents/skills/ ``` Install only the skills relevant to your project. For VCL work, `falco` and `xvcl` are the most useful. For Fastly Compute, use `fastly-cli` and either `viceroy` or `fastlike`. The [toolkit README](https://github.com/fastly/fastly-agent-toolkit#available-skills) describes every available skill. ### Claude Code ### Fastly Agent Toolkit To install the Fastly Agent Toolkit as a plugin, run the following command: ```term copy $ claude plugin install fastly-agent-toolkit@claude-plugins-official ``` If the command output asks you to, run `/reload-plugins` in Claude Code to load the plugin. ### Fastly MCP server To add the Fastly MCP server, run the following command: ```term copy $ claude mcp add fastly -- bunx -p @fastly/mcp fastly-mcp ``` Make sure `FASTLY_API_TOKEN` is set in the environment that starts Claude Code, or configure the token in your Claude Code MCP settings. ### Codex ### Fastly Agent Toolkit To install the Fastly Agent Toolkit as a plugin, run the following commands: ```term copy $ codex plugin marketplace add https://github.com/fastly/fastly-agent-toolkit.git $ codex plugin add fastly-agent-toolkit@fastly-agent-toolkit ``` ### Fastly MCP server To install the Fastly MCP server as a plugin, run the following commands: ```term copy $ codex plugin marketplace add https://github.com/fastly/mcp $ codex plugin add fastly-mcp@fastly-local ``` The Fastly MCP plugin launches the server with `bunx` and enables secret encryption. If you only have Node.js, use `npx` as the launch command. Make sure the launcher is available on the `PATH` that Codex uses. The plugin passes `FASTLY_API_TOKEN` to the server from the environment that starts Codex. Set the variable there, and then restart Codex. ### Cursor ### Fastly Agent Toolkit Cursor loads skills from the `.agents/skills/` directory. Copy the Fastly Agent Toolkit skills you need into that directory. ### Fastly MCP server Add the [standard MCP configuration](https://www.fastly.com/documentation/reference/agent-setup#standard-mcp-configuration) to `~/.cursor/mcp.json` to make the server available in every project, or to `.cursor/mcp.json` in a single project. In a project file, reference the environment variable instead of the token: ```json { "mcpServers": { "fastly": { "type": "stdio", "command": "bunx", "args": ["-p", "@fastly/mcp", "fastly-mcp"], "env": { "FASTLY_API_TOKEN": "${env:FASTLY_API_TOKEN}" } } } } ``` ### GitHub Copilot ### Fastly Agent Toolkit GitHub Copilot loads skills from the `.agents/skills/` directory. Copy the Fastly Agent Toolkit skills you need into that directory. ### Fastly MCP server To add the Fastly MCP server to GitHub Copilot in Visual Studio Code, add the following configuration to `.vscode/mcp.json` in your project. Visual Studio Code uses a `servers` key instead of `mcpServers`. With this configuration, Visual Studio Code prompts you for the token when the server starts, so the token isn't stored in the file: ```json { "inputs": [ { "type": "promptString", "id": "fastly-api-token", "description": "Fastly API token", "password": true } ], "servers": { "fastly": { "type": "stdio", "command": "bunx", "args": ["-p", "@fastly/mcp", "fastly-mcp"], "env": { "FASTLY_API_TOKEN": "${input:fastly-api-token}" } } } } ``` Visual Studio Code may ask you to confirm that you trust the server before it starts. ### Gemini CLI ### Fastly Agent Toolkit Gemini CLI loads skills from the `.agents/skills/` directory. Copy the Fastly Agent Toolkit skills you need into that directory. Alternatively, link the whole toolkit as a Gemini CLI extension by running the following commands: ```term copy $ cd ~/fastly-agent-toolkit $ gemini extensions link . ``` Restart Gemini CLI to load the extension. ### Fastly MCP server Add the [standard MCP configuration](https://www.fastly.com/documentation/reference/agent-setup#standard-mcp-configuration) to `~/.gemini/settings.json`. Keep the `env` block: Gemini CLI doesn't pass environment variables with `TOKEN` in their names to MCP servers unless the configuration sets them. To read the token from your shell, set its value to `"$FASTLY_API_TOKEN"`. ### OpenCode ### Fastly Agent Toolkit OpenCode loads skills from the `.agents/skills/` directory. Copy the Fastly Agent Toolkit skills you need into that directory. ### Fastly MCP server Add the following configuration to `opencode.json` in your project, or to `~/.config/opencode/opencode.json` to make the server available in every project. This example reads the token from the `FASTLY_API_TOKEN` environment variable: ```json { "mcp": { "fastly": { "type": "local", "command": ["bunx", "-p", "@fastly/mcp", "fastly-mcp"], "environment": { "FASTLY_API_TOKEN": "{env:FASTLY_API_TOKEN}" } } } } ``` ### Cline ### Fastly Agent Toolkit Cline loads skills from the `.cline/skills/` directory in your project, or from `~/.cline/skills/` for every project. Copy the Fastly Agent Toolkit skills you need into one of those directories. ### Fastly MCP server In the Cline panel, click the **MCP Servers** icon, open the **Configure** tab, and click **Configure MCP Servers**. Then add the [standard MCP configuration](https://www.fastly.com/documentation/reference/agent-setup#standard-mcp-configuration). ### Claude Desktop ### Fastly Agent Toolkit The Fastly Agent Toolkit is intended for coding environments that can read project files and run commands. For Claude Desktop, use the Fastly MCP server instead. ### Fastly MCP server Add the [standard MCP configuration](https://www.fastly.com/documentation/reference/agent-setup#standard-mcp-configuration) to Claude Desktop's configuration file, and then restart Claude Desktop. The file is usually in one of the following locations: - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json` - **Linux:** `~/.config/Claude/claude_desktop_config.json` ### Other agents ### Fastly Agent Toolkit For Qwen Code, Swival, and other agents, refer to the [Fastly Agent Toolkit README](https://github.com/fastly/fastly-agent-toolkit#usage). The README also describes installing skills with the [`skills` CLI](https://github.com/vercel-labs/skills), which installs skills into the `.agents/skills/` directory and links them into agent-specific directories. ### Fastly MCP server For Qwen Code, Swival, and other agents, refer to the [Fastly MCP server README](https://github.com/fastly/mcp#installation). ## Verifying the setup To confirm your agent can work with your Fastly account, ask it a read-only question, such as: ```plain List my Fastly services and show the active version for each one. Do not make changes. ``` If the agent lists your services, it's using your Fastly credentials. If it can't, check the following: - **Fastly Agent Toolkit:** run `fastly whoami` in the shell where your agent runs commands to check that the Fastly CLI is authenticated there. - **Fastly MCP server:** check that `FASTLY_API_TOKEN` is set in the environment the MCP server runs in. The server can search its bundled API documentation without a token, but it needs one to call the Fastly API. ## About the Fastly MCP server The [Fastly MCP server](https://github.com/fastly/mcp) is a Model Context Protocol (MCP) server that lets your agent call the Fastly API directly, without the Fastly CLI. Through the server, your agent can look up services, check traffic, manage dictionaries and access control lists (ACLs), and make configuration changes when you ask it to. The Fastly MCP server requires either [Bun](https://bun.sh/) or [Node.js](https://nodejs.org/) 24.12.0 or later. It reads your Fastly API token from the `FASTLY_API_TOKEN` environment variable. Set the variable in the shell that starts your agent or in your agent's user-level MCP configuration. If you add the server to a configuration file inside your project, reference the environment variable instead of the token itself. The Fastly MCP server can also encrypt secrets, such as tokens, in API responses before your agent sees them. The [Fastly MCP server README](https://github.com/fastly/mcp#secret-encryption) explains how to enable secret encryption and describes its limitations. ### Standard MCP configuration Many MCP clients use the following JSON block to start the Fastly MCP server: ```json { "mcpServers": { "fastly": { "command": "bunx", "args": ["-p", "@fastly/mcp", "fastly-mcp"], "env": { "FASTLY_API_TOKEN": "your-token-here" } } } } ``` If the configuration file already contains an `mcpServers` object, add the `fastly` entry to it. To use Node.js instead of Bun, replace `bunx` with `npx`. If the shell that starts your agent already exports `FASTLY_API_TOKEN`, some agents let you omit the `env` block. Gemini CLI requires it. ## Working safely with your agent A Fastly API token gives your agent access to your production configuration, and a token with write access lets it make changes. Tell your agent whether it's allowed to change anything. For read-only requests, end your prompt with "Do not make changes," as in the example in [Verifying the setup](https://www.fastly.com/documentation/reference/agent-setup#verifying-the-setup). > **WARNING:** A token with the `global` scope gives your agent full control over your services, with access to every API endpoint your user role allows. Your agent could, for example, delete a service, change its domains and backends, or purge all cached content. If your agent only needs to purge content, use a token with one of the [purge scopes](https://www.fastly.com/documentation/guides/organizations-and-accounts/personal-user-profiles/managing-your-personal-api-tokens#token-scopes) instead. When you want your agent to make changes, we recommend the following: - Name the service, domain, version, dictionary, ACL, or backend the agent should work on. - Ask the agent to show the command or API call it plans to run before it makes the change. - For service configuration changes, ask the agent to clone the active service version, edit the clone, and summarize the changes before you activate it.