---
name: iblai-connect-socrata
description: "Read and write Tyler Data & Insights (Socrata) data through the Socrata Open Data API (SODA) and SODA Producer API and expose it to an ibl.ai agent as an MCP tool. Use when the user asks an agent to work with Tyler Data & Insights (Socrata) data, or to set up a Tyler Data & Insights (Socrata) MCP connection on ibl.ai."
metadata:
  kind: guide
---

# Tyler Data & Insights (Socrata) connector for AI agents

> A starting point maintained on ibl.ai at https://ibl.ai/developer/connectors/socrata — not part of the iblai/vibe repository. Checked against Tyler Technologies' documentation on October 20, 2026; test it against your own Tyler Data & Insights (Socrata) setup before you rely on it.

Tyler Data & Insights, built on Socrata, hosts government open data portals and internal data platforms. Datasets such as budgets, 311 requests, permits, crime incidents and inspections are published as queryable tables.

## Auth & conventions

- **API:** Socrata Open Data API (SODA) and SODA Producer API (REST). Query any dataset with SoQL (a SQL-like language) via SODA 3.0 query and export endpoints, or the legacy /resource/ endpoint. The Producer API upserts, replaces and deletes rows in datasets you can edit.
- **Base URL:** https://{domain}/api/v3/views/{IDENTIFIER}/query.json (legacy: https://{domain}/resource/{IDENTIFIER}.json)
- **Access:** Public, self-serve. Anyone can register an app token in their Socrata profile settings. SODA 3.0 query requests must carry an app token or user authentication. Writes require a user with edit rights on the dataset.
- **Auth:** App token (X-App-Token header); HTTP Basic with API key ID/secret; OAuth 2.0. App tokens identify the application for throttling. Writes and private data need a user via HTTP Basic (API key/secret recommended for scripts) or OAuth 2.0 for web apps. All authenticated requests must use https.
- **Limits:** Requests with an app token are not throttled unless abusive; without one, requests from shared IPs are throttled (HTTP 429). Default page is 1,000 rows; SODA 2.0 caps $limit at 50,000, 2.1 and 3.0 have no maximum. Query timeout defaults to 600s.
- Keep Tyler Data & Insights (Socrata) credentials in environment variables or the ibl.ai credential store. Never print a token in chat and never commit one to a file.
- Destructive or outward-facing calls are marked **Confirm with the user first** — do.

## Reads

- **Dataset rows** — POST /api/v3/views/{id}/query.json with a SoQL query and page {pageNumber, pageSize}.
- **Dataset export** — /api/v3/views/{id}/export.{format} returns the whole dataset (JSON, CSV, GeoJSON and other formats).
- **Filtered or aggregated rows** — SoQL SELECT, WHERE, GROUP BY, ORDER BY, LIMIT and OFFSET over a dataset.
- **Legacy resource endpoint** — GET /resource/{id}.json with $select, $where, $limit, $offset parameters.

## Writes

- **Upsert rows** — POST rows to the dataset endpoint as an authenticated user with edit access; existing IDs update, new ones insert.
- **Replace dataset rows** — PUT to the dataset endpoint replaces rows in bulk. **Confirm with the user first.**
- **Delete rows** — DELETE a single row, or include ":deleted": true for a row ID in an upsert payload. **Confirm with the user first.**

## Expose it to an ibl.ai agent (MCP)

Tyler Technologies did not publish an MCP server of its own when this skill was checked. Host a small MCP server that wraps the calls above, then register it below.

First install the ibl.ai platform skills and connect your organization (writes `IBLAI_ORG`, `IBLAI_USERNAME` and `IBLAI_API_KEY` to `.env`):

```bash
npx skills add iblai/vibe --all
# then, in your coding agent:
/iblai-api-login
```

Every call below sends `Authorization: Api-Token $IBLAI_API_KEY`.

1. **Register the server** — `POST https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mcp-servers/` with `name`, `url`, `transport` (`sse` | `websocket` | `streamable_http`) and `auth_type` (`none` | `token` | `oauth2`). Capture the returned `id`.
   - For an API key or service credential use `auth_type=token` with `auth_scope=platform` for one key across the organization, or scope it to a single agent for one key per agent.
2. **Create the connection** — `POST https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mcp-server-connections/` with `server`, `scope` (`platform` | `mentor` | `user`), `auth_type`, and either `credentials` + `authorization_scheme` or a `connected_service` id for OAuth. Credentials are masked on read; never send a masked value back.
3. **Enable it on the agent** — `GET https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mentors/{agent_id}/settings/`, add `mcp-tool` to `tool_slugs` and the server id to `mcp_servers`, then `PATCH` the full lists back. They are replaced, not merged.

Full reference: https://ibl.ai/developer/platform/mcp/mcp-connections and the `/iblai-api-agent-mcp` skill.

## Example prompts

- "Count 311 service requests by type for the last 30 days on data.cityofchicago.org"
- "Pull this year's building permits over $1M as CSV from our open data portal"
- "Upsert today's inspection results into our restaurant inspections dataset"
- "Find the top 10 vendors by total payments in the city checkbook dataset"

## Guardrails

- Open data portals publish public records. Internal or private datasets on the platform can hold PII or sensitive agency data, so access should follow each dataset's permissions.
- Request the narrowest Tyler Data & Insights (Socrata) scopes or role the task needs, and prefer a read-only credential for agents that only answer questions.
- Return the fields the user asked for, not whole records; do not paste personal data into chat that the user did not request.
- Before any write, show the user exactly what will change and wait for a yes.
- Respect the documented limits above: page through results and back off on rate-limit responses instead of retrying in a loop.

## References

- Socrata Developers (SODA): https://dev.socrata.com/
- SODA API endpoints: https://dev.socrata.com/docs/endpoints.html
- Authentication: https://dev.socrata.com/docs/authentication.html
- This connector on ibl.ai: https://ibl.ai/developer/connectors/socrata
- ibl.ai MCP server connections: https://ibl.ai/developer/platform/mcp/mcp-connections