Skip to help content
AICD API
Connection guide

Agent and MCP setup

Set up a Streamable HTTP connection and follow the current access rules.

Reviewed Oct 23, 2026Owner: AICD APISource: cdee385Read as Markdown

Access and support status

The authenticated server route is built at https://aicdapi.com/api/v1/mcp. It requires a bearer key; one key carries both the records API and MCP read access.

A civic tool call runs on an account with current paid data access. Paid access continues through the end of the paid period after a cancellation, and a civic call without it returns beta_unavailable and tells the client not to retry automatically. The two report tools need the account's current paid access and no report permission: a report takes no payment and does not use the plan allowance. Named desktop and command-line clients are unverified.

Connection values

  • Transport: Streamable HTTP over HTTPS.
  • Server URL: https://aicdapi.com/api/v1/mcp.
  • Authentication: Authorization bearer header from AICD_API_KEY.
  • Current protocol version: 2026-07-28.
  • The server keeps a stateless compatibility path for the 2025-06-18 initialize flow.
  • Maximum MCP request body: 65,536 bytes. Civic data tool timeout: 10 seconds. The report submission itself has a separate 8 KiB limit.
Generic client valuesjson
{
  "url": "https://aicdapi.com/api/v1/mcp",
  "bearerTokenEnvVar": "AICD_API_KEY"
}

Safe setup

  1. Create one key for this agent; a new key carries mcp:read. Creating or rotating a key needs current paid data access; listing and revoking keys do not.
  2. Put the secret in the client's secret field or AICD_API_KEY environment variable.
  3. Add the HTTPS server URL and reconnect the client.
  4. List tools before making a call, and check each returned source link.
  5. Revoke the key when you remove the client.

Report a data gap

Report calls need a key that is active on an account with current paid access. They need no report permission. Report submission is a write action.

Submitting or checking a report does not consume a paid data call. Keep the same idempotencyToken for retries of the same report.

Links

Search one classified topic

The search_agenda tool requires query. Add topicSlug to select an exact topic slug. A topic slug uses 1 to 64 lowercase letters, numbers, underscores, or hyphens.

Each result includes publisher names and the source type. It also includes the source freshness status and the last successful check time when one exists.

Results are paged. Each response returns nextCursor. Pass it back as cursor with the same query, filters, and limit to read the next page; it is null on the last page.

A malformed cursor, or one that does not match the same query, filters, and limit, is rejected as invalid_cursor before the search runs and before any payment.

A cursor whose anchored record has moved or vanished can only be detected after the search. A paid read can then report read_failed with no payment settled; a direct read reports invalid_cursor. Start a new search without a cursor.

  • The query, topic, jurisdiction, and date filters are combined with AND.
  • The ranker reads at most the best 200 matching candidates before ranking. candidateLimitReached true means that window filled up, so more matching records may exist beyond it. Narrow the query or date range to reach them. Pagination is never a complete export.
  • Paging is not a snapshot. Records ingested between pages can appear or shift.
  • A result must have a classified topic match for the exact topicSlug. A word in an agenda title or body does not create that match by itself.
  • Freshness can be healthy, stale, failing, or inactive. Healthy, stale, and failing use the source's expected check interval, last success, and latest failure. Inactive means the source endpoint is no longer scheduled, while its historical records stay searchable.
  • lastSuccessfulCheckAt is the time of the latest successful source check. It is not proof that the source was complete or that a record was published at that time.
  • An empty result does not prove that no government action occurred. Check coverage, the topic slug, the date range, and the government source.
Search one classified topicjson
{
  "query": "data center",
  "topicSlug": "development_approval",
  "jurisdictionSlug": "dallas",
  "fromDate": "2026-09-01",
  "toDate": "2026-09-10"
}

Client compatibility

  • Generic Streamable HTTP configuration is documented from the server contract.
  • AICD API has not verified Codex, Claude, ChatGPT, or any other named client.
  • Client-specific menus and configuration shapes can change. Follow the client maker's current documentation.

Links