INTEGRATIONS / MODEL CONTEXT PROTOCOL

Milten MCP: website audits in your AI assistant

Connect Codex, Cursor or Claude Code to your saved Milten audits. Through the Model Context Protocol (MCP), your assistant can read website performance metrics and get optimization recommendations backed by data from the report.

Set up Milten MCP Tool reference

Milten MCP

HTTP

How your assistant uses a Milten audit

Find the audit
list_audits
Read the measurements
get_audit_report
Get an optimization plan
get_optimization_plan

Read-only access

Reads saved audits without starting new scans, changing projects or charging Milten tokens.

How to connect to Milten MCP

Milten MCP runs on a remote server. Add its URL and an access token to a client that supports Streamable HTTP and custom Authorization headers. No local Milten package is needed.

Server URL: https://milten.io/mcp
Authentication: Authorization: Bearer <PAT>

What you need

You need a Milten account and a personal access token. To read a report, use an existing audit owned by that account or run a new one on the Milten website.

Codex

Replace <PAT> with your token secret and run the entire block in Bash or Zsh. It adds the server and saves Authorization in http_headers in the Codex configuration file (~/.codex/config.toml by default). Running it again replaces the milten settings. Restart Codex. The file contains your secret: do not publish it.

Terminal

codex mcp add milten --url https://milten.io/mcp &&
cat >> "${CODEX_HOME:-$HOME/.codex}/config.toml" <<'EOF'

[mcp_servers.milten.http_headers]
Authorization = "Bearer <PAT>"
EOF

Client documentation ↗

Cursor

Add the milten entry to mcpServers in ~/.cursor/mcp.json to use it across projects, or in .cursor/mcp.json for one project. Keep any existing server entries.

For examples that use MILTEN_MCP_TOKEN, set the token as that environment variable’s value before starting your client. Restart the client after changing it. A variable set in a terminal is not automatically available to an app opened from the desktop.

.cursor/mcp.json

{
  "mcpServers": {
    "milten": {
      "url": "https://milten.io/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MILTEN_MCP_TOKEN}"
      }
    }
  }
}

Client documentation ↗

Claude Code

Merge this entry into the project’s .mcp.json. Claude Code expands the environment variable when it starts; approve the project server when prompted.

.mcp.json

{
  "mcpServers": {
    "milten": {
      "type": "http",
      "url": "https://milten.io/mcp",
      "headers": {
        "Authorization": "Bearer ${MILTEN_MCP_TOKEN}"
      }
    }
  }
}

Client documentation ↗

Check that the six tools are available

Enable milten in your MCP client. It should discover list_audits, get_audit_report, get_optimization_plan, get_audit_section, compare_audits and get_monitoring_history. Start with list_audits and use an auditId from the response. An empty list is valid if there are no audits yet.

How to get a Milten access token

Create and manage personal access tokens (PATs) in your profile, under API keys. Milten MCP accepts them through Authorization: Bearer. Browser cookies and OAuth login are not supported by the MCP endpoint.

Create an access token

Open API keys in your profile. Choose a name and expiration period, then select Create token.

Open API keys

Copy the secret now: it is shown only once. Store it securely and pass it to your client using one of the setup methods above. The token id remains visible in the list for revocation.

The token grants audits:read for your own audits. name is required (up to 100 bytes); expiresAt is a future RFC 3339 timestamp, at most 366 days away.

List and revoke tokens

In API keys you can view token names, permissions, expiration dates and last use, or revoke a token. For programmatic management, GET /v1/personal-access-tokens/ returns metadata without secrets; DELETE with the token {id} revokes it and returns 204 No Content. These account API requests require your signed-in browser session.

Account API

GET /v1/personal-access-tokens/
DELETE /v1/personal-access-tokens/{id}

MCP tools: audits, reports and optimization plans

Your MCP client passes these JSON arguments to tools/call. For report and plan requests, replace the example UUID with an auditId from list_audits. Use the audit ID, not the website URL.

list_audits

Find audits owned by the authenticated user. Optionally narrow the list to one project.

Arguments: All fields are optional. projectId: project UUID; page: integer ≥ 1 (default 1); limit: integer 1–50 (default 10).
Response: audits contains auditId, url, operation, status and createdAt, with projectId and error when present. count is the total; page and limit describe pagination. If truncated is true, retry with a smaller limit. Status is running, completed or failed.

list_audits · JSON

{
  "page": 1,
  "limit": 10
}

get_audit_report

Read every saved report section and a concise metrics summary.

Arguments: auditId: required audit UUID from list_audits.
Response: audit contains metadata; filling contains all saved sections as {type, data}, including Lighthouse, HAR, CrUX and llmAdvice. analysis adds a metrics and findings summary. trustNote marks site content as untrusted data. The default response data limit is 1 MiB; exceeding it returns an error, not a truncated report.

get_audit_report · JSON

{
  "auditId": "123e4567-e89b-42d3-a456-426614174000"
}

get_optimization_plan

Read the saved llmAdvice plan shown in the audit report. MCP does not generate new recommendations or call an LLM.

Arguments: auditId: required UUID; focus: all (default), lcp, inp, cls or backend; limit: integer 1–25 (default 10).
Response: plan contains source, summary, recommendations and truncated. Recommendation order and fields are preserved: priority (critical, medium or low), metrics, metricSavings, title, resources, evidence, action, effect and verification. focus filters by metrics; backend means TTFB. When limit shortens the list, truncated is true. Legacy text plans appear in output without filtering. If no plan is saved, read diagnostic.

get_optimization_plan · JSON

{
  "auditId": "123e4567-e89b-42d3-a456-426614174000",
  "focus": "lcp",
  "limit": 3
}

get_audit_section

Reads the latest saved report section. Large arrays can be retrieved in pages.

Arguments: auditId and section are required. section is a filling type, such as har. Optional path is a JSON Pointer, such as /log/entries. For arrays: offset starts at 0; limit is 1–200 (default 50). Omit pagination for other data.
Response: data preserves original fields and null. Arrays include total, nextOffset and truncated; follow nextOffset until truncated is false. An oversized response returns an error: select a narrower path or reduce limit.

get_audit_section · JSON

{
  "auditId": "123e4567-e89b-42d3-a456-426614174000",
  "section": "har",
  "path": "/log/entries",
  "limit": 20
}

compare_audits

Compares two of your audits for the same URL and audit type: measurements, threshold findings and saved recommendations.

Arguments: baselineAuditId is the original audit; candidateAuditId is the later audit. Get both UUIDs from list_audits. Lab metrics are supported for basic, inp and ttfb.
Response: delta = candidate − baseline; missing values are null. Check comparable and warnings. findings groups are added, resolved, persisting and uncompared. Recommendations match by exact title; both saved plans are included.

compare_audits · JSON

{
  "baselineAuditId": "123e4567-e89b-42d3-a456-426614174000",
  "candidateAuditId": "e6723288-f28c-4b62-8a4e-7dc395958c0c"
}

get_monitoring_history

Returns saved measurements for your monitoring page, newest first. Does not start a check.

Arguments: monitoringUnitId is required: the Core UUID of the monitoring page (coreMonitoringUnitId), not auditId. dateFrom and dateTo are inclusive RFC 3339 boundaries; default is the last 30 days. page starts at 1; limit is 1–50 (default 20).
Response: results include timestamps, metrics, device, region and affectedAlert. The response includes count and hasMore. Reuse returned dateFrom and dateTo for subsequent pages. Legacy zeros may mean missing data; INP is a lab measurement, not CrUX p75.

get_monitoring_history · JSON

{
  "monitoringUnitId": "e09aa948-a541-4404-bcdc-9e5621c11891",
  "page": 1,
  "limit": 20
}

Example prompts for your AI assistant

After connecting, use these messages in your assistant’s chat. The assistant calls the MCP tools and explains their results; the messages are not separate server commands.

Show my Milten audits and find the latest completed audit for example.com.
Read that report. Which metrics point to slow loading? Include their values and units.
Get an optimization plan focused on LCP. If the report supports them, suggest up to three changes and explain how to verify each one.

What the connection can access

The token identifies your account, so userId is not a tool argument. A project filter only narrows your own audit list; it does not grant access to other users’ audits. MCP reads saved data and cannot start a scan. Treat text from an audited website as report data, never as instructions for your agent.

Troubleshooting

404 / HTML instead of JSON

Confirm the MCP endpoint is enabled for your environment. Use /mcp exactly, without a trailing slash or a language prefix. The documentation page is a different URL.

401 unauthorized

Check Authorization: Bearer and your token secret. If Codex shows failed (0 tools), repeat the setup with a valid token and restart Codex. Replace expired or revoked tokens. OAuth login is not supported.

403 origin forbidden

For a browser-based client, its origin must be allowed by the MCP server. Contact Milten with the client name and origin; do not send your token.

429 rate limit exceeded

Reduce request frequency and retry later. The default server limit is 60 requests per minute per token; an environment may configure a different limit.

audit not found / invalid arguments

Use an audit UUID from your own list_audits response. A missing audit and another user’s audit both return audit not found. Check pagination, focus and limit values.

Empty metrics or recommendations

Check audit.status and diagnostic. The report may have no supported metrics or saved llmAdvice. Recommendations may also be empty when none match focus. This does not confirm that the site has no issues.

503 / temporarily unavailable

The authentication or audit service is temporarily unavailable. Retry later; if it persists, contact support.

How to connect to Milten MCP

Milten MCP runs on a remote server. Add its URL and an access token to a client that supports Streamable HTTP and custom Authorization headers. No local Milten package is needed.

Server URL

https://milten.io/mcp

Authentication

Authorization: Bearer <PAT>

What you need

You need a Milten account and a personal access token. To read a report, use an existing audit owned by that account or run a new one on the Milten website.

Codex

Terminal

codex mcp add milten --url https://milten.io/mcp &&
cat >> "${CODEX_HOME:-$HOME/.codex}/config.toml" <<'EOF'

[mcp_servers.milten.http_headers]
Authorization = "Bearer <PAT>"
EOF

Client documentation ↗

Cursor

Add the milten entry to mcpServers in ~/.cursor/mcp.json to use it across projects, or in .cursor/mcp.json for one project. Keep any existing server entries.

.cursor/mcp.json

{
  "mcpServers": {
    "milten": {
      "url": "https://milten.io/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MILTEN_MCP_TOKEN}"
      }
    }
  }
}

Client documentation ↗

Claude Code

Merge this entry into the project’s .mcp.json. Claude Code expands the environment variable when it starts; approve the project server when prompted.

.mcp.json

{
  "mcpServers": {
    "milten": {
      "type": "http",
      "url": "https://milten.io/mcp",
      "headers": {
        "Authorization": "Bearer ${MILTEN_MCP_TOKEN}"
      }
    }
  }
}

Client documentation ↗

Check that the six tools are available

How to get a Milten access token

Create an access token

Open API keys in your profile. Choose a name and expiration period, then select Create token.

Open API keys

Copy the secret now: it is shown only once. Store it securely and pass it to your client using one of the setup methods above. The token id remains visible in the list for revocation.

The token grants audits:read for your own audits. name is required (up to 100 bytes); expiresAt is a future RFC 3339 timestamp, at most 366 days away.

List and revoke tokens

Account API

GET /v1/personal-access-tokens/
DELETE /v1/personal-access-tokens/{id}

MCP tools: audits, reports and optimization plans

Your MCP client passes these JSON arguments to tools/call. For report and plan requests, replace the example UUID with an auditId from list_audits. Use the audit ID, not the website URL.

list_audits

Find audits owned by the authenticated user. Optionally narrow the list to one project.

Arguments: All fields are optional. projectId: project UUID; page: integer ≥ 1 (default 1); limit: integer 1–50 (default 10).
Response: audits contains auditId, url, operation, status and createdAt, with projectId and error when present. count is the total; page and limit describe pagination. If truncated is true, retry with a smaller limit. Status is running, completed or failed.

list_audits · JSON

{
  "page": 1,
  "limit": 10
}

get_audit_report

Read every saved report section and a concise metrics summary.

Arguments: auditId: required audit UUID from list_audits.
Response: audit contains metadata; filling contains all saved sections as {type, data}, including Lighthouse, HAR, CrUX and llmAdvice. analysis adds a metrics and findings summary. trustNote marks site content as untrusted data. The default response data limit is 1 MiB; exceeding it returns an error, not a truncated report.

get_audit_report · JSON

{
  "auditId": "123e4567-e89b-42d3-a456-426614174000"
}

get_optimization_plan

Read the saved llmAdvice plan shown in the audit report. MCP does not generate new recommendations or call an LLM.

Arguments: auditId: required UUID; focus: all (default), lcp, inp, cls or backend; limit: integer 1–25 (default 10).
Response: plan contains source, summary, recommendations and truncated. Recommendation order and fields are preserved: priority (critical, medium or low), metrics, metricSavings, title, resources, evidence, action, effect and verification. focus filters by metrics; backend means TTFB. When limit shortens the list, truncated is true. Legacy text plans appear in output without filtering. If no plan is saved, read diagnostic.

get_optimization_plan · JSON

{
  "auditId": "123e4567-e89b-42d3-a456-426614174000",
  "focus": "lcp",
  "limit": 3
}

get_audit_section

Reads the latest saved report section. Large arrays can be retrieved in pages.

Arguments: auditId and section are required. section is a filling type, such as har. Optional path is a JSON Pointer, such as /log/entries. For arrays: offset starts at 0; limit is 1–200 (default 50). Omit pagination for other data.
Response: data preserves original fields and null. Arrays include total, nextOffset and truncated; follow nextOffset until truncated is false. An oversized response returns an error: select a narrower path or reduce limit.

get_audit_section · JSON

{
  "auditId": "123e4567-e89b-42d3-a456-426614174000",
  "section": "har",
  "path": "/log/entries",
  "limit": 20
}

compare_audits

Compares two of your audits for the same URL and audit type: measurements, threshold findings and saved recommendations.

Arguments: baselineAuditId is the original audit; candidateAuditId is the later audit. Get both UUIDs from list_audits. Lab metrics are supported for basic, inp and ttfb.
Response: delta = candidate − baseline; missing values are null. Check comparable and warnings. findings groups are added, resolved, persisting and uncompared. Recommendations match by exact title; both saved plans are included.

compare_audits · JSON

{
  "baselineAuditId": "123e4567-e89b-42d3-a456-426614174000",
  "candidateAuditId": "e6723288-f28c-4b62-8a4e-7dc395958c0c"
}

get_monitoring_history

Returns saved measurements for your monitoring page, newest first. Does not start a check.

Arguments: monitoringUnitId is required: the Core UUID of the monitoring page (coreMonitoringUnitId), not auditId. dateFrom and dateTo are inclusive RFC 3339 boundaries; default is the last 30 days. page starts at 1; limit is 1–50 (default 20).
Response: results include timestamps, metrics, device, region and affectedAlert. The response includes count and hasMore. Reuse returned dateFrom and dateTo for subsequent pages. Legacy zeros may mean missing data; INP is a lab measurement, not CrUX p75.

get_monitoring_history · JSON

{
  "monitoringUnitId": "e09aa948-a541-4404-bcdc-9e5621c11891",
  "page": 1,
  "limit": 20
}

Example prompts for your AI assistant

After connecting, use these messages in your assistant’s chat. The assistant calls the MCP tools and explains their results; the messages are not separate server commands.

Show my Milten audits and find the latest completed audit for example.com.

Read that report. Which metrics point to slow loading? Include their values and units.

Get an optimization plan focused on LCP. If the report supports them, suggest up to three changes and explain how to verify each one.

What the connection can access

Troubleshooting

404 / HTML instead of JSON

Confirm the MCP endpoint is enabled for your environment. Use /mcp exactly, without a trailing slash or a language prefix. The documentation page is a different URL.

401 unauthorized

403 origin forbidden

For a browser-based client, its origin must be allowed by the MCP server. Contact Milten with the client name and origin; do not send your token.

429 rate limit exceeded

Reduce request frequency and retry later. The default server limit is 60 requests per minute per token; an environment may configure a different limit.

audit not found / invalid arguments

Use an audit UUID from your own list_audits response. A missing audit and another user’s audit both return audit not found. Check pagination, focus and limit values.

Empty metrics or recommendations

503 / temporarily unavailable

The authentication or audit service is temporarily unavailable. Retry later; if it persists, contact support.

Milten MCP: website audits in your AI assistant

How to connect to Milten MCP

What you need

Check that the six tools are available

How to get a Milten access token

Create an access token

MCP tools: audits, reports and optimization plans

list_audits

get_audit_report

get_optimization_plan

get_audit_section

compare_audits

get_monitoring_history

Example prompts for your AI assistant

What the connection can access

Troubleshooting

We use cookies

Milten MCP: website audits in your AI assistant

How to connect to Milten MCP

What you need

Check that the six tools are available

How to get a Milten access token

Create an access token

MCP tools: audits, reports and optimization plans

list_audits

get_audit_report

get_optimization_plan

get_audit_section

compare_audits

get_monitoring_history

Example prompts for your AI assistant

What the connection can access

Troubleshooting

We use cookies