# MCP server

> Registry search, batch, coverage and map tools for MCP clients, authenticated with your API key.

- **HTML:** https://offendersearch.app/docs/ai/mcp
- **Base URL (live):** https://api.offendersearch.app — live keys (`os_live_…`)
- **Base URL (sandbox):** https://sandbox.offendersearch.app — test keys (`os_test_…`), never billed
- **Authentication:** `X-API-Key` request header
- **OpenAPI:** https://offendersearch.app/openapi.json · https://offendersearch.app/openapi.yaml
- **Docs index for agents:** https://offendersearch.app/llms.txt

## Status and access

> **Private beta.** The MCP server is built and in private beta. Ask for access from the [MCP server page](/mcp-server) or [support@offendersearch.app](mailto:support@offendersearch.app); it uses the same API key and billing as the REST API.

## Client configuration

*MCP client config (Claude Desktop, Cursor and compatible clients)*
```json
{
  "mcpServers": {
    "offendersearch": {
      "url": "https://mcp.offendersearch.app",
      "headers": { "X-API-Key": "os_live_••••" }
    }
  }
}
```

Use a test key (`os_test_…`) while developing; it is never billed. Keep the key in the client's secret configuration, never in a shared prompt.

## Tools

| Tool | Does | REST equivalent | Billing |
| --- | --- | --- | --- |
| `search_offenders` | Search all 58 US registries by name, date of birth or age, address, ZIP or a lat/lng radius; returns the same scored, cited records as the REST API. | `POST /v1/search` | One search per call |
| `batch_search` | Up to 1,000 people in one call, one scored row out per row in. | `POST /v1/batch` | One search per row |
| `get_registry_coverage` | The catalog of all 58 registries with scope, legal status and health, so the agent can say what it searched. | `GET /v1/sources` | Free |
| `map_viewport` | What to draw for one map view: clusters, pins, names by zoom. | `POST /v1/map/viewport` | One map request |
| `map_group` | The people behind one pin, paged. | `GET /v1/map/groups/{groupId}` | One map request per page |
| `map_area` | The same answer for a drawn polygon or buffered line. | `POST /v1/map/area` | One map request |
| `map_route` | Counts per leg and stop along a route, no names. | `POST /v1/map/route` | Route units |
| `map_open_record` | The full record behind a marker. | `GET /v1/map/records/{markerId}` | One record open |

Tool results are the REST envelopes: the agent reads `status`, `counts`, `sourceStatus[]` and `records[]` exactly as a program would. Criminal records and monitoring are not yet exposed as MCP tools; use the REST API for them.

## Related

- [Agents & tool calling](https://offendersearch.app/docs/ai/agents)
- [Sex Offender Search API](https://offendersearch.app/docs/sex-offender)
- [Offender Map API](https://offendersearch.app/docs/map)