Setting up AI agents to work with Fastly

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 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 installed and authenticated, your agent can use these skills to work with your Fastly account.
• Fastly documentation: the Markdown version of our documentation 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 instead.

Before you begin

Before you set up your agent, make sure you have the following:

• The Fastly CLI: install the Fastly CLI and run fastly auth login to authenticate it with a Fastly API token. 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 or Viceroy. Each skill describes its own prerequisites.

Setting up with a prompt

To set up your agent automatically, copy the following prompt and send it to your agent.

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=<URL-encoded terms>&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.

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

$ 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 describes every available skill.

Claude Code

$ claude plugin install fastly-agent-toolkit@claude-plugins-official

$ claude mcp add fastly -- bunx -p @fastly/mcp fastly-mcp

Codex

$ codex plugin marketplace add https://github.com/fastly/fastly-agent-toolkit.git
$ codex plugin add fastly-agent-toolkit@fastly-agent-toolkit

$ codex plugin marketplace add https://github.com/fastly/mcp
$ codex plugin add fastly-mcp@fastly-local

Cursor

1
2
3
4
5
6
7
8
9
10
11
12

{
  "mcpServers": {
    "fastly": {
      "type": "stdio",
      "command": "bunx",
      "args": ["-p", "@fastly/mcp", "fastly-mcp"],
      "env": {
        "FASTLY_API_TOKEN": "${env:FASTLY_API_TOKEN}"
      }
    }
  }
}

GitHub Copilot

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

{
  "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}"
      }
    }
  }
}

Gemini CLI

$ cd ~/fastly-agent-toolkit
$ gemini extensions link .

OpenCode

1
2
3
4
5
6
7
8
9
10
11

{
  "mcp": {
    "fastly": {
      "type": "local",
      "command": ["bunx", "-p", "@fastly/mcp", "fastly-mcp"],
      "environment": {
        "FASTLY_API_TOKEN": "{env:FASTLY_API_TOKEN}"
      }
    }
  }
}

Cline

Claude Desktop

Other agents

Verifying the setup

To confirm your agent can work with your Fastly account, ask it a read-only question, such as:

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 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 or Node.js 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 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:

1
2
3
4
5
6
7
8
9
10
11

{
  "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.

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.