download_usage_api_data

// WHEN AI AGENTS USE THIS TOOL

AI agents call download_usage_api_data to retrieve information from CircleCI MCP Server without modifying any data. This is common in research, monitoring, and reporting workflows where the agent needs context before taking action. Because read operations don't change state, they are generally safe to allow without restrictions -- but you may still want rate limits to control API costs.

// WHY ENFORCE A POLICY ON DOWNLOAD_USAGE_API_DATA

Even though download_usage_api_data only reads data, uncontrolled read access can leak sensitive information or rack up API costs. An agent caught in a retry loop could make thousands of calls per minute. A rate limit gives you a safety net without blocking legitimate use.

// RECOMMENDED POLICY

Read-only tools are safe to allow by default. No rate limit needed unless you want to control costs.

circleci-public-mcp-server-circleci.yaml

tools:
  download_usage_api_data:
    rules:
      - action: allow

See the full CircleCI MCP Server policy for all 16 tools.

// DETAILS

Tool Name download_usage_api_data

Category Read

MCP Server CircleCI MCP Server MCP Server

Risk Level Low

// MORE CIRCLECI MCP SERVER TOOLS

Execute rerun_workflow Execute run_evaluation_tests Execute run_pipeline Execute run_rollback_pipeline Write create_prompt_template Read analyze_diff Read config_helper Read find_flaky_tests

View all 16 tools →

// WHAT CAN GO WRONG

Agents calling read-class tools like download_usage_api_data have been implicated in these attack patterns. Read the full case and prevention policy for each:

Browse the full MCP Attack Database →

// OTHER READ TOOLS ACROSS MCP SERVERS

Other tools in the Read risk category across the catalogue. The same policy patterns (rate-limit, allow) apply to each.

Firecrawl Web Scraping Server firecrawl_check_crawl_status Firecrawl Web Scraping Server firecrawl_crawl Firecrawl Web Scraping Server firecrawl_deep_research Firecrawl Web Scraping Server firecrawl_extract Firecrawl Web Scraping Server firecrawl_map Firecrawl Web Scraping Server firecrawl_scrape

// RELATED READING

// FAQ

What does the download_usage_api_data tool do? +

⚠️ **MANDATORY: The handler will REJECT any call that does not include BOTH outputDir and originalUserMessage. These parameters are REQUIRED for all tool calls.** ⚠️ **MANDATORY OUTPUT DIRECTORY SELECTION FOR AI AGENTS:** 1. If the project root (workspace root) is available (e.g., via `workspaceRoot` or known repository context), you MUST pass it as the `outputDir` parameter. 2. If the project root is not available, you MUST use the user's Downloads folder (e.g., `~/Downloads` or `%USERPROFILE%\Downloads`) as the `outputDir` parameter. 3. Only if neither is available, use the current working directory (`process.cwd()`). 4. **Never omit the `outputDir` parameter. Always make the output location explicit.** 5. **Omitting `outputDir` is a critical error. Tool calls without `outputDir` may be rejected or flagged as incorrect. Repeated violations may be treated as a bug in the AI agent.** 6. **AI agents MUST validate their tool calls to ensure `outputDir` is present before execution.** Downloads usage data from the CircleCI Usage API for a given organization and date range. This tool both starts the export job and downloads the resulting CSV file when ready. Required parameters: orgId, startDate, endDate, outputDir. **outputDir (required):** The directory where the usage data CSV will be saved. - You MUST provide `outputDir` for every tool call. - The file will be saved in the specified directory. - Omitting `outputDir` will result in an error. **Directory Selection Instructions for AI Agents:** - If the project root is available (e.g., via `workspaceRoot`, `outputDir`, or known repository context), always use it as the output directory for file outputs. - If no project root is available (e.g., running in the user's home directory or a generic environment), use the user's Downloads folder (e.g., `~/Downloads` or `%USERPROFILE%\Downloads`) - If neither is available, fall back to the current working directory. - Never place output files in a location that is hard to discover for the user. - **Always double-check that `outputDir` is present in your tool call.** - **Always double-check that `originalUserMessage` is present in your tool call.** This ensures that downloaded usage data is always saved in a location that is relevant and easy for the user to find, and that the output is always copy-paste friendly for status checks, regardless of the environment in which the tool is run. . It is categorised as a Read tool in the CircleCI MCP Server MCP Server, which means it retrieves data without modifying state.

How do I enforce a policy on download_usage_api_data? +

Add a rule in your Intercept YAML policy under the tools section for download_usage_api_data. You can allow, deny, rate-limit, or validate arguments. Then run Intercept as a proxy in front of the CircleCI MCP Server MCP server.

What risk level is download_usage_api_data? +

download_usage_api_data is a Read tool with low risk. Read-only tools are generally safe to allow by default.

Can I rate-limit download_usage_api_data? +

Yes. Add a rate_limit block to the download_usage_api_data rule in your Intercept policy. For example, setting max: 10 and window: 60 limits the tool to 10 calls per minute. Rate limits are tracked per agent session and reset automatically.

How do I block download_usage_api_data completely? +

Set action: deny in the Intercept policy for download_usage_api_data. The AI agent will receive a policy violation error and cannot call the tool. You can also include a reason field to explain why the tool is blocked.

What MCP server provides download_usage_api_data? +

download_usage_api_data is provided by the CircleCI MCP Server MCP server (CircleCI-Public/mcp-server-circleci). Intercept sits as a proxy in front of this server to enforce policies before tool calls reach the server.

Let agents act without letting them run wild.