Skip to main content
describe the analysis you want in Claude. Edgeful builds and validates it, Claude shows you the methodology and sample, and you can revise it before saving. the saved report opens in Edgeful with ticker, session, and date controls.

connect and allow writes

  1. connect the Edgeful MCP server using your active API-enabled Edgeful account.
  2. writes are on by default. to check them, open the API dashboard: under let AI agents make changes in your account, allow changes through the MCP connector covers AI apps you signed in to and allow changes through your API key covers a client that uses a key. the same permission covers the account settings tools.
  3. start a conversation with the Edgeful tools enabled.
both permissions start on and can be turned off from the dashboard at any time. a regenerated key starts with writes on. you can still read standard reports, list saved custom reports, and read stored results with writes off.

try a report

Claude calls build_custom_report with the brief. if Edgeful needs details, Claude asks the returned question and continues with revise_custom_report. builds can take a few minutes. review the methodology, assumptions, sample, and accepted inputs. ask for changes in the same conversation. when it looks right, say:
save_custom_report publishes the reviewed artifact immediately and returns its definition_id. the report appears in my custom reports in Edgeful AI, marked built via API. its builder conversation is also available in Edgeful AI history.

choose charts and layout

describe how you want to see the result when you build or revise it. for example:
reports can include KPI rows, bar, stacked bar, line, area and pie charts, tables, and explanations in a chosen order. saved runs reproduce that layout from the calculated values without another AI call. reports without a valid layout keep the summary-and-table view.

run on another selection

ask Claude to run the report on another ticker or date range. run_custom_report accepts either a saved definition_id, or the conversation_id and exact successful message_id from a draft. draft runs do not save a report. optional controls contain ticker, market_type, session, start_date, and end_date. dates use YYYY-MM-DD. the report’s market and granularity remain locked. session can change unless its methodology requires a fixed session. you can request a date range beyond the builder’s sample window, subject to your plan and execution limits. saved runs are cached for the same inputs and completed data. a new selection shows loading in Edgeful until it finishes. there is no refresh schedule or older-result placeholder. if a tool returns running, read that run with get_custom_report_run after the suggested wait, or repeat run_custom_report with the same inputs. for a retryable failure, supply its run_id as retry_of_run_id.

find, read, and delete

  • list_custom_reports returns your saved reports and their methodology. when has_more is true, pass next_offset as the next call’s offset.
  • get_custom_report_latest_result reads the latest successful stored result without computing. check its actual effective_controls, data_through, and computed_at: it may be for a different selection. no_result means no saved run has completed yet.
  • results reach Claude 100 rows at a time with total_rows. when next_row_offset is present, get_custom_report_run with the result’s run_id and that row_offset reads the next rows, so Claude can work through every row of a saved report’s run. a draft’s rows past the first 100 are readable once it is saved.
  • delete_custom_report removes the saved report and its stored runs when you request deletion. the original builder conversation remains.
everything except building and revising is also a REST route for your own code, called with your API key: list your saved reports, read the latest result, run a saved report on new inputs and read the run by its id, save a reviewed draft, and delete a report. REST results carry every stored row. see custom reports over REST.

usage and results

builds and revisions use your Edgeful AI allowance. runs execute frozen code without an AI call; saved cache hits do not consume a new run. builds, revisions, saves and deletes share a limit of 10 per minute and 100 per hour across your connections and keys; runs have their own limit of 60 per minute and 600 per hour. a run that needs a fresh computation also uses your run allowance of 200 per hour, and fresh computations run one at a time per account. follow the returned wait time when limited. tool responses include summary data, at most 100 detail rows, a total row count, truncation information, and presentation blocks when available. large responses may contain fewer blocks or rows; open the report from my custom reports in Edgeful AI for the complete result. generated code and raw market-data rows are not returned. Edgeful generates the report code from your brief; the tools do not accept executable code from Claude.