# MCP

The same evidence is available to AI agents through the [Model Context Protocol](https://modelcontextprotocol.io). The tools call the same core as the REST API, so an agent gets exactly the objects, hashes, and URLs a person sees.

- **Streamable HTTP:** `https://agents.newyorkeverydaylawreference.com/mcp`
- **stdio:** `npm run mcp:stdio` (reads the data directory directly; set `PUBLIC_BASE_URL` for canonical URLs)

## Tools

| Tool | Arguments | Returns |
| --- | --- | --- |
| `search_evidence` | `q`, `jurisdiction?`, `as_of?`, `type?`, `limit?`, `cursor?` | Ranked compact objects and the interpretation used |
| `get_evidence` | `id`, `as_of?`, `version?`, `view?` | One object (full view by default) |
| `get_relationships` | `from?`, `to?`, `relation?`, `as_of?` | Relationships between objects |
| `build_evidence_packet` | `question`, `jurisdiction?`, `as_of?`, `topics?` | An evidence packet |
| `resolve_citation` | `citation`, `content_hash?` | Whether a citation is current, revised, superseded, altered, or unknown |

Every tool returns `structuredContent` (validated against its output schema), the same JSON as text, and `_meta.request_id`. All tools are read-only.

Errors are tool results with `isError: true`. Arguments that don't match the input schema get the SDK's "Input validation error" message. Anything caught after that (an unknown ID, a missing version, a cursor from another query) returns a JSON body with the same stable `code` as the REST API (`NOT_FOUND`, `VERSION_NOT_FOUND`, `INVALID_REQUEST`).

## Cursor

`.cursor/mcp.json` in your project, or `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "nyc-evidence": {
      "url": "https://agents.newyorkeverydaylawreference.com/mcp"
    }
  }
}
```

Or run over stdio from a clone of this repository:

```json
{
  "mcpServers": {
    "nyc-evidence": {
      "command": "npx",
      "args": ["tsx", "apps/mcp-stdio/main.ts"],
      "cwd": "/path/to/nyc-evidence"
    }
  }
}
```

## Claude

Claude Code:

```bash
claude mcp add --transport http nyc-evidence https://agents.newyorkeverydaylawreference.com/mcp
```

Claude Desktop (`claude_desktop_config.json`), over stdio:

```json
{
  "mcpServers": {
    "nyc-evidence": {
      "command": "npx",
      "args": ["tsx", "/path/to/nyc-evidence/apps/mcp-stdio/main.ts"]
    }
  }
}
```

## Suggested agent workflow

1. Call `build_evidence_packet` with the research question and the date of the events (`as_of`).
2. Read `status` and `limitations` before anything else. `INSUFFICIENT_EVIDENCE` means say so; don't fill the gap from memory.
3. Quote `statement` and `passages` rather than paraphrasing, and cite each object with its `cite_as` block.
4. When handing evidence to another agent or a person, pass the `cite_as` blocks. The receiver can call `resolve_citation` (or fetch the URL and recompute the hash) to confirm nothing changed.
5. Don't turn the evidence into advice about someone's situation. See [acceptable use](https://agents.newyorkeverydaylawreference.com/docs/acceptable-use).

The [two-agent example](https://agents.newyorkeverydaylawreference.com/examples) shows this end to end.