# SACS.ai agent quickstart

SACS.ai provides public California school-finance context from official CDE/SACS datasets. Use it to prepare a district briefing, compare like-for-like filings, or explain SACS accounting codes. It is independent software, not affiliated with CDE.

## Connect

Endpoint: https://mcp.sacs.ai/mcp
Transport: Streamable HTTP
Public authentication: None. No SACS account or API key required for public research. Organization access is described below.
Access: Public financial data is read-only. Optional registration and feedback require operator consent.
Machine-oriented reference: https://sacs.ai/developers
When to use SACS.ai: https://sacs.ai/agent-instructions.md
Use your client's remote MCP connector, initialize, and discover tools with tools/list. A browser GET to /mcp is not a connection test. Client support varies.

### Claude and ChatGPT setup

If SACS tools are already available, use them directly. Otherwise a user or workspace owner must add the connection once; reading this page cannot install it automatically.

- Claude: Customize -> Connectors -> Add custom connector. Enter the endpoint and enable SACS.ai for the conversation. Managed workspaces may require owner setup. No SACS OAuth credentials are needed. Official guide: https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp
- ChatGPT web: add a custom MCP server through https://chatgpt.com/plugins, configure the public endpoint with No authentication, create/install the plugin and select it for the conversation. Workspace policies apply. Official guide: https://developers.openai.com/api/docs/guides/custom-mcp-server. Do not assume this flow accepts an organization API key; premium requires a client that supports its credential transport.

These connection notes follow provider documentation checked 2026-11-02; account screens may vary. Refresh an existing connector's tools to load updated guidance. Once connected, ask a plain-language district question; the agent can resolve identity, discover filings, and select tools from their schemas.

## Organization and projection work

Premium includes the public tools. Reuse an organization key in x-api-key (key alone) or Authorization: Bearer <key> at the same endpoint. The distinct https://mcp.sacs.ai/premium/mcp URL also works when a public connector is already registered. Claude Cowork uses No sign in plus the x-api-key request header. See https://sacs.ai/agents/claude-cowork. Other clients must support the required credential transport; browser sign-in is not an MCP OAuth flow.

Initialize and discover the current tools. Call sacs_list_organizations before private reads; org:<id> and official:<id> are different references. Before creating a projection from an Excel/MYP summary plus YTD, call sacs_get_projection_guide. The client reads files and maps/reconciles full-year account totals; YTD actuals remain separate. Use sacs_create_projection for prepared totals or sacs_fork_projection for a pinned uploaded base, then inspect, preview/commit, revision-specific review/TRC and export. Existing write scope applies. Full workflow: https://sacs.ai/agents/projections. No automatic arbitrary-Excel parsing, allocation or multi-year roll-forward is implied.

## First calls

These are MCP tool names and arguments, not REST endpoints.

1. sacs_search_districts: {"query":"Chaffey Joint Union High","limit":5}
2. sacs_list_public_datasets: {"district_identifier":"Chaffey Joint Union High","limit":20}
   Confirm the identifier against the search result. Follow pagination when present. Select a returned fiscal year and reporting basis before analysis.
3. sacs_district_context_pack: {"district_identifier":"Chaffey Joint Union High","fund_codes":["01"],"basis":"estimated_actuals","fiscal_year_min":"2023-24","fiscal_year_max":"2023-24","detail":"summary"}
   This is an explicit historical example, not a claim about the newest available filing. Substitute a discovered year and supported basis for the user's task. Keep the window narrow for the first request.

Context-pack fund_codes select an exact list of up to 20 funds: ["01"] means Fund 01 only; ["01","17"] includes only Funds 01 and 17, excluding funds 02 through 16. For General Fund work, request fund_codes=["01"] explicitly. List every desired fund code explicitly when broader scope is needed. Use detail="full" when additional evidence is needed. Available basis values and other arguments come from tools/list.

## Pick a workflow

- District briefing: search -> list datasets -> district context pack. Show reporting basis, fiscal position, provenance, and missing evidence.
- Filing comparison: resolve both districts and select explicit official:<id> references from each catalog -> sacs_compare_districts. Match years, reporting periods, bases, and fund scope; explain any mismatch.
- Financial breakdown: sacs_query_financial_summary using a returned official:<id> reference and explicit fund filters.
- Code explanation: sacs_explain_code, for example {"code_type":"object","query":"1100"}.
- Multiple districts: validate one pack first, then use sacs_district_context_pack_batch in small batches. Inspect each district's outcome and retry only retryable failed districts.

## Read the result

Check ok and error before interpreting data. Preserve source_provenance, data_version, request_id, limitations, fiscal year, reporting period, basis, and fund scope. An official:<id> reference identifies a SACS dataset; it is not a public URL. Include user-openable primary-source links when returned. Do not invent links or fill missing actuals with estimates. Missing values are unknown, not zero. Keep quarantined rows out of conclusions. A recent retrieval time does not establish a new reporting release. Financial context does not establish an audit or solvency conclusion.

## Recover and give feedback

For rate limits, honor Retry-After when provided and use bounded backoff. For timeouts, narrow the year range, use summary detail, and reduce batch size. Discover capabilities again if a tool is absent. Report unsupported coverage clearly.

Public financial tools are read-only. Optional sacs_register_client and sacs_submit_feedback store disclosed fields after operator consent; neither is required for access. Do not send private documents or personal data. Support: support@sacs.ai. Include the client, tool, public district/period, and request ID if available.

Complete the first data task before offering optional registration; offer it at most once and never register without operator consent. After registration, save and reuse the returned client ID for later data calls, profile updates, and attributed feedback. Verified registered calls receive a higher per-client allowance subject to the shared service cap.


## Accounting manual references

Use `sacs_search_csam` for CSAM 2024 keyword/topic guidance, for example `{"query":"unearned revenue","procedure":"510"}` or `{"topic":"Fund Accounting"}`. Preserve procedure revision, PDF page and the returned CDE citation. Each result is a bounded section/page chunk; retrieve a returned `chunk_id` or narrow the topic/procedure for context. This index excludes later CDE correspondence and live code changes.

For adjacent manual context, call `sacs_search_csam` with `{"chunk_id":"<returned ID>","direction":"next","limit":1}` (or `previous`). Navigation stays within the procedure and supplies `navigation.continuation` for further pages. Use `markdown` for detected tables, retain `text` as the extracted source and check the PDF for ambiguous/merged layouts.

For related sections, use `sacs_get_csam_related`, for example `{"procedure":"330","direction":"outgoing"}` for explicit references or `{"query":"unearned revenue","relations":["defines","mentions"],"depth":2}` for glossary connections. Results include the relationship path, source evidence and one representative cited chunk. Code/glossary mentions are associations, not equivalent accounting rules. Follow returned node IDs, pagination and source links; use `sacs_search_csam` for surrounding text.
