Developer docs

Build agents with NYC records that explain themselves.

Connect an MCP-compatible assistant or application to Akil's source-backed NYC public-record layer. Agents can start from real-world anchors and retrieve structured records with source context, caveats, and follow-up paths.

Quickstart →Example agentsStructured output
ENDPOINT LIVE
https://mcp.askakil.ai/mcp
Package: akil-mcp@2.5.1
Authorization: Bearer $AKIL_API_KEY
MCP-Protocol: streamable-http
Content-Type: application/json

Client support varies by AI product. Interactive users authorize in the client. Backend integrations store API keys outside application code.

01 · Quickstart

Add the connection, then let the agent find the public-record path.

Most users should not choose individual data categories manually. Add the Akil MCP connection in your client, authorize access, and let the connected assistant discover the right tools for the question.

1

Connect the endpoint

Register Akil as a remote MCP server in an MCP-compatible assistant, agent framework, or workspace connector.

2

Authorize access

Interactive users sign in through Akil. Approved backend integrations send an Akil API key as a bearer token.

3

Start with the platform guide

For orientation, ask the assistant to call akil_platform_guide before browsing the full tool list.

4

Route the investigation

For a specific civic question, use akil_overview to choose the right toolset, anchor plan, caveats, and follow-up tools.

5

Render the result

Responses include text plus structured packets clients can render as tables, maps, charts, or follow-up workflows.

Start here: Use akil_platform_guide to explain what Akil can do, what it covers, and how I should start.
02 · Example agents

What developers can build with Akil.

Akil is useful as a direct connector inside an assistant, but it can also power narrower agents that sit inside a firm, newsroom, nonprofit, agency, or internal workflow.

▣

Permit & location diligence

FOR
Architects, operators, expeditors, brokers
DOES
Checks property, permit, inspection, license, and location records before a lease, renovation, or opening decision.
STARTS WITH
AddressBBLBINlicense type
03 · Authentication

Sign-in for users. Bearer tokens for approved integrations.

Akil supports interactive authorization for assistant clients and API-key access for selected developer or partner workflows.

MODE
METHOD
USE
Interactive client
OAuth sign-in
Claude, ChatGPT, and other user-facing assistants.
Developer / partner key
Bearer token
Backend jobs, private agents, internal tools, partner access.
Credential storage
Env variable
Store keys in a secret manager or env var, never in public frontend code.
mcp.config.tomlCONFIG
[mcp_servers.akil]
url = "https://mcp.askakil.ai/mcp"
bearer_token_env_var = "AKIL_API_KEY"
.envSECRET
AKIL_API_KEY=ak_live_...
Plain English: the API key is the credential. "Bearer token" describes how your client sends it in the authorization header.
04 · Core concepts

Tools, resources, anchors, interpretation, and packets.

Akil is organized to help agents retrieve records, preserve identifiers, carry civic scope, explain source context, and continue the user's workflow without losing the thread.

01

Entry points

Use akil_platform_guide for connector orientation and akil_overview for civic investigation routing.

02

Tools

Read-only public-record lookups. The assistant calls these for property, money, licensing, organization, lobbying, spatial, or other civic records.

03

Resources

Guide documents that teach agents how to use Akil for workflow-aware tasks like business opening, regulated locations, and visualization.

04

Anchors

Stable identifiers carried across records: BBL, EIN, agency, district, license, application ID, vendor, person, location, time.

05

Interpretation

Plain-English context that helps agents avoid overreading a status, filing, deadline, amount, application, or empty result.

06

Packets

Structured payloads (akil.table.v1, akil.map.v1, akil.chart.v1) with anchors, columns, source context, caveats, and nextTools agent orchestration can use.

05 · Guide resources

Workflow guidance lives inside the server.

Clients that support MCP resources can read these guides and use them to decide what to call next.

akil://guide/platformStart-here platform guide for what Akil is, what it covers, how to begin, and what trust limits apply.
akil://guide/welcomeWelcome surface that separates platform orientation from civic-investigation routing.
akil://guide/interpretationHow to read public-record statuses, amounts, dates, no-row findings, and source caveats.
akil://guide/coverageWhat Akil covers, what each source can miss, and how to treat coverage limits.
akil://guide/entity-resolutionHow to handle names, addresses, BBLs, EINs, agencies, vendors, and candidate matches.
akil://guide/anchorsHow records connect through BBL, EIN, agency, district, license, and time.
akil://guide/visualizationHow clients can use map, chart, and table packets.
akil://guide/business-openingHow to reason through permits, licenses, inspections, and location checks.
akil://guide/regulated-locationHow to approach alcohol, cannabis, inspection, and location-sensitive questions.
06 · Structured output

Responses can carry records, context, and next steps.

Text remains available for every client. Structured clients can also render richer artifacts using packet metadata, anchors, source notes, and caveats.

FIELD
TYPE
MEANING
text
string
Human-readable summary or answer.
structuredContent
object
Machine-readable table, map, or chart payload.
_meta.akilType
enum
akil.table.v1, akil.map.v1, akil.chart.v1
anchors
object
Reusable identifiers the assistant should carry forward.
columns
array
Column defs with roles: anchor, status, date, money, geo, source.
interpretation
object
Source value, plain-English meaning, caveat, or next verification step where the tool provides it.
nextTools
array
Suggested follow-up tools for orchestration.
response.jsonakil.table.v1
{
  content: [
    { type: "text", text: "5 permits found..." }
  ],
  structuredContent: {
    rows: [...],
    columns: [
      { key: "permitNumber", role: "anchor" },
      { key: "status", role: "status" },
      { key: "filingDate", role: "date" }
    ],
    anchors: {
      bbl: "1012970023",
      timeWindow: "last 5 years"
    },
    interpretation: {
      status: "source status explained for this record",
      caveat: "permit records are signals, not legal-use approval"
    },
    nextTools: [
      "akil_re_property_report",
      "akil_certificate_of_occupancy"
    ]
  },
  _meta: {
    akilType: "akil.table.v1"
  }
}
07 · Workflow patterns

Common starting points for agent orchestration.

These are examples of how an assistant should think with Akil — not rigid scripts.

USER ASKS
"What records should I check before signing this lease?"
RETURNS
Licenses, inspections, permits, location context, next checks.
08 · Trust checks

Use Akil as a layer that is checked for source-aware behavior.

Akil's repeatable checks focus on public-record interpretation. They do not claim perfect data. They check that the answer keeps source meaning, coverage limits, identity uncertainty, metric caveats, regulatory boundaries, and degraded paths visible.

Sources

Source and caveat checks

Checks high-risk answer behavior: source attribution, coverage disclosure, freshness notes, result caps, caveats, and verification paths.

Limits

Coverage and no-result checks

Checks that broad, capped, empty, or degraded responses stay bounded to the searched source, filters, and window.

Roles

Identity and regulatory checks

Checks that known tricky records stay separated instead of becoming false clearance, ownership, payment, influence, or absence claims.

Public trust status: https://mcp.askakil.ai/trust/status
09 · Best practices

How to get better answers from Akil.

  • 01Start with a stable anchor: BBL for property, EIN for orgs, agency for public money, license/app ID for regulated businesses.
  • 02Constrain broad questions with a time window, geography, record type, or result limit.
  • 03Use structured packet anchors and nextTools before starting a new search from scratch.
  • 04Treat empty results as a finding, not a failure - explain the searched source and filters.
  • 05Keep opportunities, awards, contracts, payments, filings, registrations, and licenses separate unless the source connects them.
  • 06Do not treat a filing, pending application, approved application, permit, signoff, license, or no-row result as final legal clearance.
  • 07Akil retrieves public records. It is not a substitute for legal, architectural, financial, or permitting advice.
Limits. Akil retrieves and organizes public records. It does not replace professional judgment, legal advice, permitting counsel, architectural review, or financial advice.
Caveats. Data availability and freshness vary by source. Agents should cite the source, date fields, filters, and any empty-result context when answering.

Ready to connect?

Use the endpoint in your MCP-compatible client and authorize through Akil when your client supports custom connectors.

← Back to MCP overview