Page Speed Analysis via MCP Agents

Evaluating and optimizing web performance historically required hopping between code editors, web browsers, and performance measurement suites. Now, with the emergence of the Model Context Protocol (MCP), developers can invoke performance audits directly from within their development environments. Implementing page speed MCP tools enables AI agents to check Core Web Vitals, identify render-blocking assets, and return structured suggestions without forcing you to context-switch out of your IDE.

ToolYour provides a remote MCP server so AI agents can use API-backed tools with the same API key and monthly quota as the REST API. This integration bridges the gap between code generation and performance monitoring. By routing speed diagnostic queries through your agent, you receive direct, actionable feedback on how code changes impact real-world performance metrics.

For a full structural overview of how agent-based operations handle complex multi-tool challenges, you can refer to our guide on how solve_task works on ToolYour MCP at the ToolYour MCP developers guide.

---

Why agents run performance checks

Running web performance checks directly through an AI agent in your IDE transforms a slow, manual QA cycle into an automated, feedback-driven development process. Instead of editing code, deploying to a staging server, opening a browser tab, and executing a performance test, the entire workflow can be initiated with a simple text command inside your development client.

There are several reasons why developers connect performance audits to automated agents:

• Context Preservation: Developers maintain focus within their primary workspace (such as Cursor, Claude Desktop, or Claude Code) without having to manage external diagnostic tools.
• Immediate Code-Level Synthesis: When an agent runs a page speed analysis and identifies an issue, it doesn't just display a list of errors. Because the agent has access to your local workspace, it can immediately correlate those errors to specific files—such as finding a large unoptimized image or a render-blocking stylesheet—and offer to rewrite the code to resolve the bottleneck.
• Structured Data Over Visual Clutter: Traditional browser tests provide complex visual graphs and heavy dashboards. Agents parse raw API payloads to isolate the specific performance metrics that matter most, outputting them in clean, human-readable markdown.

---

Connect MCP for page speed MCP analysis

To begin running performance checks through your agent, you must connect your workspace to the ToolYour remote MCP server. ToolYour hosts its remote MCP gateway at https://api.toolyour.com/mcp, exposing a robust suite of API-backed utilities designed for AI assistant integration.

You can find more background on the underlying standard on the official Model Context Protocol website.

Authentication and Quotas

ToolYour remote MCP operations are secured using your standard developer API key. Both REST API calls and MCP tool executions share the same API key and monthly quota.

• Key Format: Your API key is prefixed with ty_.
• Authentication Header: The server expects your key to be passed via the X-Api-Key header.
• Free Plan Quota: The free plan provides 500 successful requests per month, shared across REST and MCP. This quota resets on the 1st of each calendar month.
• Throughput Limits: The free plan enforces a rate limit of 5 successful requests per minute.
• Key Sharing: If you generate multiple API keys under a single account, they will all share the same monthly quota pool.
• Accounting Rules: Only successful tool calls count against your monthly allowance. Invalid requests generally do not consume credits.
• Weighted Billing: Exploring the MCP tool catalog is free. Running a tool through MCP consumes weighted credits ranging from 1 to 10 credits per call, depending on the computational cost of the specific tool.
• Usage Blocks: Once you exhaust your monthly quota, plan caps block further requests until you upgrade your subscription or until the next calendar month begins.

Client Integration

Instead of hardcoding static configuration blocks in this guide, you should retrieve the interactive, step-by-step connection instructions directly from the ToolYour MCP setup page. This page provides live, client-specific setups for Cursor, Claude Desktop, and other MCP-compliant environments.

When configuring your client, you will use the X-Api-Key header to pass your active credential. Here is an example of the headers used during authentication:

X-Api-Key: ty_your_active_developer_key_here

---

Example performance goals

Once your agent is connected to the ToolYour remote MCP server, you can begin issuing performance-related goals. The agent uses the primary orchestrating tool, solve_task, to process your natural language instructions, identify the correct performance tools, execute the audits, and format the findings.

Understanding solve_task Maturity

Before using the meta-tool workflow, it is important to understand its current development stage. The solve_task tool is in an early phase. Routing, agent workflows, and general tool coverage are actively improving as ToolYour upgrades existing tools and adds new MCP capabilities.

Because solve_task is still maturing, receiving a response with status: suggest is common today. For production-critical environments or automated pipeline scripts where deterministic outcomes are required, you should bypass autonomous routing. Instead, construct a structured pipeline using the standard step-by-step path:

1. Call discover_tools to find the correct speed performance tool.
2. Call get_tool_schema to verify the precise inputs and arguments required.
3. Call invoke_tool to run the speed audit with your parameters.

Formulating the Agent Goal

For interactive development and exploration within your IDE, you can prompt solve_task with specific, descriptive performance goals. Below is an example of the JSON payload structure your agent uses when submitting a task:

{
  "task": "Analyze the page speed of the landing page at `https://yoursite.com/blog` for mobile devices. Focus on identifying the Largest Contentful Paint (LCP) and any render-blocking CSS resources.",
  "context": {
    "target_device": "mobile",
    "depth": "single-page"
  }
}

The agent processes this request, calls the appropriate underlying page speed analysis tool, compiles the raw data, and delivers a structured report directly inside your chat panel.

---

Reading agent output

An agent executing a page speed task successfully will translate complex performance data into a concise, action-oriented summary. When the workflow completes, your agent displays a structured breakdown of the target page's performance footprint.

Below is an example of what success looks like when reading the agent's output in your IDE:

Speed Audit Summary: https://yoursite.com/blog

• Performance Score: 78 / 100 (Needs Improvement)
• Device Audited: Mobile

Core Web Vitals Checklist

• Largest Contentful Paint (LCP): 3.2s — Fails recommended 2.5s threshold.
• Cumulative Layout Shift (CLS): 0.05 — Good. Minimal unexpected layout movement.
• Total Blocking Time (TBT): 410ms — Slightly high. Main thread is busy during load.

High-Impact Opportunities

1. Render-Blocking Resources:

   • https://yoursite.com/assets/css/main-theme.css (Deploys 140KB of unused styles)
   • Agent Action: Combine or defer non-critical CSS rules.

2. Unoptimized Media:

   • The hero image loaded at https://yoursite.com/images/banner.png lacks explicit width and height dimensions and should be converted to modern formats (like WebP or AVIF).

Because the agent has direct access to your local workspace, it can immediately offer to resolve these bottlenecks. For instance, it can look at your local code files and suggest:

"I see that main-theme.css is imported synchronously in your layout.tsx file. Would you like me to refactor this component to lazy-load non-critical stylesheets and add explicit dimensions to the hero image component?"

---

Browser alternative

While running performance audits from your IDE provides a highly integrated developer experience, there are times when a visual web-based alternative is more appropriate. For example, you might want to share a visual report with a client, run a quick check without consuming your API key quota, or test a page before you have configured your local MCP environment.

ToolYour provides a suite of visual tools directly through the web interface. These browser-based tools are free and do not require any signup.

If you prefer a manual, visual performance evaluation over an automated agent workflow, you can run an instant test using the ToolYour free page speed test online.

Choosing the Right Interface

To help determine when to use the browser-based tool versus the MCP agent integration, consider the following trade-offs:

• Use the Browser Tool when:
  • You need to generate quick, visual reports to share with non-technical stakeholders.
  • You want to run tests without using your monthly API developer quota.
  • You are working on a machine that does not have your local development environment or IDE setup.
• Use the MCP Agent when:
  • You are actively writing code and want to verify performance changes on a page without leaving your IDE.
  • You want an AI assistant to analyze the performance results and apply the code fixes directly to your local workspace files.
  • You are automating testing workflows using developer scripts or terminal commands.

---

FAQ

Do MCP requests consume a separate quota from the REST API?

No. The ToolYour REST API and MCP share the exact same monthly quota and API key. Executing an MCP tool consumes weighted credits from your unified monthly allowance.

What happens if I exceed my monthly request limit on the free tier?

The free plan provides 500 successful requests per month. If you hit this limit, plan caps block further requests across both the REST API and the MCP server. No further requests can be processed until you upgrade your plan or wait for the quota to reset.

When does my monthly quota reset?

Your quota resets automatically on the 1st of each calendar month.

Can I share my API quota across multiple developer keys?

Yes. You can generate multiple API keys under a single ToolYour account to use across different development environments, but they will all draw from the same shared monthly quota.

Is there a cost to explore the ToolYour MCP catalog?

No. Browsing the tool catalog, querying available tools, and exploring schemas is completely free and does not consume your quota. Running actual diagnostic tools, however, will charge weighted credits to your account.

---

Conclusion

Integrating page speed analyses directly into your development workflow with the Model Context Protocol removes the friction of manual testing. By connecting to the remote ToolYour MCP gateway, you gain immediate access to performance diagnostics alongside your local codebase. This setup allows your AI agent to not only identify bottlenecks like render-blocking resources or slow Core Web Vitals but also write and implement the exact code modifications needed to resolve them.

Whether you choose to automate your diagnostics with a dedicated page speed MCP assistant directly in your IDE or opt for visual analysis, ToolYour provides the necessary tools.

To configure your performance optimization workspace, follow these next steps:

• Sign up for your developer account at the ToolYour Signup Page.
• Generate your development credentials at the ToolYour API Keys Dashboard.
• Review client configuration frameworks on the ToolYour Developers Hub.