# MCP Integration

The IntelCenter API supports the Model Context Protocol (MCP). Compatible assistants and agent clients can discover IntelCenter tools, validate their inputs, and interpret behavior annotations before calling them.

MCP is an additional interface to the same public API capabilities. API-key permissions, quotas, and data restrictions still apply.

## MCP Endpoints

| Scope | Endpoint |
|---|---|
| ICD tools | `POST https://api.intelcenter.com/mcp-icd` |
| ICD and ICDB tools permitted for the key | `POST https://api.intelcenter.com/mcp-all` |

Use a Bearer token:

```text
Authorization: Bearer YOUR_API_KEY
```

Configure the token through the client's secure credential setting. Do not paste it into prompts, chat messages, shared configuration, or source control.

## Available Tools

### Search

- `searchIcdVideos`
- `searchIcdImages`
- `searchIcdbVideos`
- `searchIcdbImages`

### Component ID Lookup

- `getIcdVideoByComponentId`
- `getIcdImageByComponentId`
- `getIcdbVideoByComponentId`
- `getIcdbImageByComponentId`

### Record Detail

- `getOneIcdVideo`
- `getOneIcdImage`
- `getOneIcdbVideo`
- `getOneIcdbImage`

### Media Access

- `getIcdVideoPlayer`
- `getIcdImageViewer`
- `getIcdbVideoPlayer`
- `getIcdbImageViewer`

### Geo Manifests

- `getIcdVideoGeoManifest`
- `getIcdImageGeoManifest`
- `getIcdbVideoGeoManifest`
- `getIcdbImageGeoManifest`

### Natural Language Search

- `searchIcdNl`
- `searchIcdbNl`

### Domain GenAI

- `icdDomainGenAiChat`
- `icdbDomainGenAiChat`

Conversation deletion remains REST-only:

- `DELETE /v1/icd/domain-genai/conversations/{conversation_id}`
- `DELETE /v1/icdb/domain-genai/conversations/{conversation_id}`

## Behavior Annotations

The server publishes behavior annotations to help compatible clients plan safe tool use.

### Retrieval Tools

Search, Component ID, detail, media-access, Geo Manifest, and Natural Language Search tools are annotated as:

- **Read-only:** yes
- **Destructive:** no
- **Idempotent:** yes
- **Open-world:** no

These operations retrieve authorized IntelCenter data and do not change conversation context.

### Domain GenAI Tools

Domain GenAI tools are annotated as:

- **Read-only:** no
- **Destructive:** no
- **Idempotent:** no
- **Open-world:** no

A successful call creates or advances conversation context and consumes the applicable credits. Repeating the same call can create another turn, so clients must not apply automatic idempotent retries.

The REST deletion operation is non-billable and idempotent, but it is intentionally not an MCP tool.

## Recommended Client Setup

1. Choose `/mcp-icd` unless the integration needs tools from both datasets.
2. Add the MCP endpoint as a remote server in the client.
3. Store the API key as a Bearer-token secret.
4. Review the tools discovered by the client.
5. Confirm the client recognizes the behavior annotations.
6. Test one ICD search before enabling broader workflows.

For a client such as ChatGPT, MCP annotations make the tool's read/write and retry behavior clearer during setup and use. They do not expand the permissions of the API key.

## Example Tool Call

A client can call `searchIcdVideos` with structured arguments such as:

```json
{
  "search": "public safety",
  "page": 1,
  "per_page": 10
}
```

If a Component ID is known, call `getIcdVideoByComponentId` instead:

```json
{
  "component_id": 123456
}
```

The number is a placeholder.

## Troubleshooting

- **401:** confirm the Bearer token and endpoint environment.
- **403:** confirm the API key's dataset and feature permissions.
- **No tools:** verify that the client is connected to `/mcp-icd` or `/mcp-all`.
- **Unexpected retry behavior:** confirm the client honors the Domain GenAI non-idempotent annotation.
- **Empty results:** check filters and permissions; an empty result does not prove that unrestricted content does not exist.