Back to Blog
mcpai-agentstutorial

Screenshot API for AI Agents: Using the FastScreenshotAPI MCP Server

FastScreenshotAPI Team5 min read

Language models are good at reading HTML and bad at knowing what a page actually looks like. Layout bugs, a cookie wall covering the content, a broken hero image, a competitor's new pricing table: an agent only sees those when it gets a picture of the rendered page.

The Model Context Protocol (MCP) is the standard way to hand an agent a tool like that. FastScreenshotAPI runs a hosted MCP server, so any MCP-compatible client can take screenshots with the same API key and quota you use for the REST API. Nothing to install, no browser to run.

What the agent gets

The server exposes four tools:

ToolWhat it does
take_screenshotCaptures a URL (or an HTML string) and returns the image to the model, plus a short text summary
batch_screenshotsQueues several URLs at once and returns job IDs
check_job_statusReports whether a queued job is done and where to fetch it
get_usageShows your plan, screenshots used this period and what is left

take_screenshot returns the image as MCP image content, so a vision-capable model can look at it directly instead of receiving a link it cannot open. It supports full_page, mobile, format (png, jpeg or webp), delay and block_cookie_banners, which is on by default, so consent popups don't end up in the agent's view.

Setup

Create a free account and copy your API key from the dashboard. The free plan includes 200 screenshots a month.

Then add the server to your MCP client's configuration. The server is remote: it lives at https://api.fastscreenshotapi.com/v1/mcp and authenticates with the X-Api-Key header.

json
{
  "mcpServers": {
    "fastscreenshot": {
      "url": "https://api.fastscreenshotapi.com/v1/mcp",
      "headers": {
        "X-Api-Key": "fsa_your_api_key_here"
      }
    }
  }
}

Where this file lives depends on the client; Cursor, for example, reads mcp.json. Restart the client after saving and the four tools should appear in its tool list.

⚠️

The key in this file can spend your screenshot quota. Keep the config out of version control, or use your client's support for environment variables or secret storage if it has it.

Prompts that work well

Once connected, you don't call tools by name. Describe the task and the agent decides when to take a screenshot:

  • "Take a screenshot of https://example.com and tell me if anything in the header looks broken."
  • "Capture our pricing page in mobile view and check whether the plan cards stack correctly."
  • "Take full-page screenshots of these five landing pages and summarize how each one presents its main offer."
  • "How many screenshots do I have left this month?"

For a single page the agent calls take_screenshot and looks at the result in the same turn. For lists it can call batch_screenshots, then check_job_status for each job.

ℹ️

Batches run as async jobs, so batch_screenshots needs a paid plan, and the number of URLs per call follows your plan's batch limit (100 on Starter up to 5,000 on Enterprise). take_screenshot works on every plan, including Free.

Calling the MCP endpoint directly

The server speaks plain JSON-RPC 2.0 over HTTP POST, which makes it easy to test with curl or to wire into your own agent framework.

List the available tools:

bash
curl -s https://api.fastscreenshotapi.com/v1/mcp \
  -H "X-Api-Key: $FASTSCREENSHOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

Take a screenshot:

bash
curl -s https://api.fastscreenshotapi.com/v1/mcp \
  -H "X-Api-Key: $FASTSCREENSHOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "take_screenshot",
      "arguments": {
        "url": "https://example.com",
        "full_page": true,
        "format": "webp"
      }
    }
  }'

The result's content array holds a text item with the capture time, size and format, followed by an image item with base64 data and its mimeType. That is exactly the shape MCP clients pass to the model.

The same call from Python, if you are building your own tool loop:

python
import base64
import os

import requests

response = requests.post(
    "https://api.fastscreenshotapi.com/v1/mcp",
    headers={"X-Api-Key": os.environ["FASTSCREENSHOT_API_KEY"]},
    json={
        "jsonrpc": "2.0",
        "id": 2,
        "method": "tools/call",
        "params": {
            "name": "take_screenshot",
            "arguments": {"url": "https://example.com", "mobile": True},
        },
    },
    timeout=90,
)
response.raise_for_status()
content = response.json()["result"]["content"]

for item in content:
    if item["type"] == "text":
        print(item["text"])
    elif item["type"] == "image":
        with open("example-mobile.png", "wb") as f:
            f.write(base64.b64decode(item["data"]))

If the capture fails, the result contains a text item that starts with Screenshot failed: and the error code, so the model can explain what went wrong instead of guessing.

MCP or the REST API?

Use the MCP server when a model decides what to capture: chat assistants, coding agents checking their own UI changes, research agents reviewing sites. Use the REST API when your code decides: scheduled monitoring, OG image generation, archiving. Both share one API key and one quota, and a screenshot costs the same either way.

Some patterns that combine both:

  • Visual QA in a coding agent. After changing a page, the agent screenshots the preview URL in desktop and mobile view and checks the result before it reports back.
  • Competitive research. The agent batches a list of competitor pages and summarizes changes in layout, messaging or pricing.
  • Support triage. Given a customer's URL, the agent captures what the customer sees, with cookie banners removed, before suggesting a fix.

Limits worth knowing

  • Screenshots taken through MCP count against the same monthly quota as REST calls. Ask the agent to run get_usage if you are unsure how much is left.
  • The model receives the image inline. Very tall full-page captures can be large; use them when the agent really needs the whole page.
  • Only publicly reachable URLs can be captured. Private IPs and internal hosts are rejected.

Next steps

Get a free API key, add the config block above to your client and ask it to screenshot a page you know well. The MCP server page has the full tool reference, and pricing covers higher volumes.