> ## Documentation Index
> Fetch the complete documentation index at: https://developers.govworx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Connect AI tools to GovWorx data using the Model Context Protocol

<Warning>
  **Early Access** - The GovWorx MCP server is currently in early access. Please work with your customer success team to obtain an API token to use the MCP server.
</Warning>

## Overview

The Model Context Protocol (MCP) is an open standard that enables AI tools and applications to connect with GovWorx data and services in a secure, standardized way. With the GovWorx MCP server, you can use AI assistants like Claude, Cursor, or other MCP-compatible tools to search events, browse media, query incidents, and access your knowledge base.

## How MCP Works

MCP provides a structured way for AI tools to interact with GovWorx:

1. **Connect** - Your AI tool connects to the GovWorx MCP server endpoint
2. **Authenticate** - The connection is authenticated using your GovWorx API token
3. **Access** - The AI tool can now search and retrieve your GovWorx data using the available tools

All data access respects your existing tenant isolation and permissions - the MCP server enforces the same security boundaries as the GovWorx web application.

## Authentication

The GovWorx MCP server uses Bearer token authentication. You'll need a GovWorx API token, which can be created in the GovWorx application under **Settings > API Tokens**.

### Required Headers

| Header          | Description                                      | Required    |
| --------------- | ------------------------------------------------ | ----------- |
| `Authorization` | Bearer token in format `Bearer <your-api-token>` | Yes         |
| `X-GW-User-Id`  | User ID for audit logging (see below)            | Recommended |

### Audit Logging

All MCP requests are logged for security and compliance purposes. The audit logs capture:

* **Token identity** - Which API token was used (token name, tenant)
* **User context** - The user ID associated with the request (from `X-GW-User-Id` header)
* **Action performed** - Which tool was called and with what parameters
* **Resources accessed** - Which events, media, incidents, or documents were retrieved
* **Timestamp** - When the request occurred

<Note>
  **Best Practice:** Always include the `X-GW-User-Id` header with the GovWorx user ID of the person using the AI tool. This ensures accurate audit trails and allows administrators to track which users are accessing data through MCP integrations.
</Note>

If `X-GW-User-Id` is not provided, requests will still be logged but will only show the API token identity, not the specific end user.

### Example Connection

```bash theme={null}
# Test connection with curl
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     https://mcp.govworx.net/sse
```

### Token Permissions

Your API token must have the appropriate permissions to use each tool:

| Permission                               | Tools Enabled                                               |
| ---------------------------------------- | ----------------------------------------------------------- |
| `BROWSE_EVENTS` or `MANAGE_EVENTS`       | searchEvents, searchMedia, searchIncidents, fetchGwResource |
| `BROWSE_KNOWLEDGE` or `MANAGE_KNOWLEDGE` | searchKnowledge                                             |

## Available Tools

The GovWorx MCP server exposes the following tools for AI assistants to use:

### searchEvents

Search for events (calls, incidents, transmissions) in your GovWorx data.

**Parameters:**

| Parameter  | Type    | Description                              |
| ---------- | ------- | ---------------------------------------- |
| `criteria` | object  | Search filters (see below)               |
| `page`     | integer | Page number (1-based, default: 1)        |
| `pageSize` | integer | Results per page (default: 10, max: 100) |

**Criteria Fields:**

| Field            | Format                           | Description                         |
| ---------------- | -------------------------------- | ----------------------------------- |
| `searchText`     | string                           | Text search against event summaries |
| `eventDateRange` | `{gte, lte}`                     | ISO-8601 date range                 |
| `eventType`      | `{eq: "value"}` or `{in: [...]}` | Filter by event type                |
| `agency`         | `{eq: "value"}` or `{in: [...]}` | Filter by agency                    |
| `priority`       | `{eq: "value"}` or `{in: [...]}` | Filter by priority                  |
| `disposition`    | `{eq: "value"}` or `{in: [...]}` | Filter by disposition               |
| `incidentNumber` | `{eq: "value"}`                  | Filter by incident number           |

**Example:**

```json theme={null}
{
  "criteria": {
    "searchText": "chest pain",
    "eventDateRange": {
      "gte": "2024-01-01",
      "lte": "2024-01-31"
    },
    "priority": { "eq": "1" }
  },
  "pageSize": 25
}
```

***

### searchMedia

Search for media records (call audio, radio transmissions) in your GovWorx data.

**Parameters:**

| Parameter  | Type    | Description                              |
| ---------- | ------- | ---------------------------------------- |
| `criteria` | object  | Search filters (see below)               |
| `page`     | integer | Page number (1-based, default: 1)        |
| `pageSize` | integer | Results per page (default: 10, max: 100) |

**Criteria Fields:**

| Field           | Format                                | Description                              |
| --------------- | ------------------------------------- | ---------------------------------------- |
| `searchText`    | string                                | Text in media context/summary            |
| `startRange`    | `{gte, lte}`                          | ISO-8601 date range for media start time |
| `durationRange` | `{gte, lte}`                          | Duration range in seconds                |
| `subType`       | `{eq: "CALL_AUDIO"}` or `{in: [...]}` | Media type filter                        |
| `channel`       | `{eq: "value"}`                       | Filter by channel                        |
| `userFirstName` | string                                | Filter by user first name                |
| `userLastName`  | string                                | Filter by user last name                 |

**Example:**

```json theme={null}
{
  "criteria": {
    "searchText": "dispatcher",
    "subType": { "in": ["CALL_AUDIO", "RADIO"] },
    "durationRange": { "gte": 60 }
  },
  "pageSize": 20
}
```

***

### searchIncidents

Search for CAD incidents in your GovWorx data.

**Parameters:**

| Parameter  | Type    | Description                              |
| ---------- | ------- | ---------------------------------------- |
| `criteria` | object  | Search filters (see below)               |
| `page`     | integer | Page number (1-based, default: 1)        |
| `pageSize` | integer | Results per page (default: 10, max: 100) |

**Criteria Fields:**

| Field         | Format                           | Description              |
| ------------- | -------------------------------- | ------------------------ |
| `searchText`  | string                           | Text in incident context |
| `startRange`  | `{gte, lte}`                     | ISO-8601 date range      |
| `priority`    | `{eq: "value"}` or `{in: [...]}` | Filter by priority       |
| `agency`      | `{eq: "value"}` or `{in: [...]}` | Filter by agency         |
| `disposition` | `{eq: "value"}` or `{in: [...]}` | Filter by disposition    |
| `callSource`  | `{eq: "value"}`                  | Filter by call source    |

***

### searchKnowledge

Search your knowledge base documents (policies, procedures, protocols).

**Parameters:**

| Parameter  | Type    | Description                                                          |
| ---------- | ------- | -------------------------------------------------------------------- |
| `criteria` | object  | Search filters (**required** - must include `searchText` or `title`) |
| `page`     | integer | Page number (1-based, default: 1)                                    |
| `pageSize` | integer | Results per page (default: 10, max: 100)                             |

**Criteria Fields:**

| Field                | Format                            | Description                                            |
| -------------------- | --------------------------------- | ------------------------------------------------------ |
| `searchText`         | string                            | Keywords to search (required if no `title`)            |
| `title`              | string                            | Filter by document title (required if no `searchText`) |
| `documentType`       | `{eq: "POLICY"}` or `{in: [...]}` | Document type filter                                   |
| `published`          | boolean                           | Filter by published status                             |
| `publishedDateRange` | `{gte, lte}`                      | ISO-8601 date range                                    |

**Example:**

```json theme={null}
{
  "criteria": {
    "searchText": "CPR protocol",
    "documentType": { "eq": "PROCEDURE" },
    "published": true
  }
}
```

***

### fetchGwResource

Fetch detailed information for specific GovWorx resources by their URI. Supports batch fetching up to 50 resources at once.

**Parameters:**

| Parameter | Type  | Description                    |
| --------- | ----- | ------------------------------ |
| `uris`    | array | Array of `gw://` URIs (max 50) |

**Supported URI Formats:**

| URI Pattern                   | Description                                              |
| ----------------------------- | -------------------------------------------------------- |
| `gw://events/{eventId}`       | Event details with transcript, personnel, incident       |
| `gw://media/{mediaId}`        | Media details with signed playback URL and transcription |
| `gw://incidents/{incidentId}` | Full incident details                                    |
| `gw://knowledge/{documentId}` | Knowledge document content                               |

**Example:**

```json theme={null}
{
  "uris": [
    "gw://events/12345",
    "gw://media/67890",
    "gw://incidents/11111"
  ]
}
```

**Response:**

```json theme={null}
{
  "gw://events/12345": { /* event data */ },
  "gw://media/67890": { /* media data with signed URL */ },
  "gw://incidents/11111": { "error": "Not found" }
}
```

***

### echo

Simple test tool to verify MCP connectivity.

**Parameters:**

| Parameter | Type   | Description          |
| --------- | ------ | -------------------- |
| `message` | string | Message to echo back |

***

### checkHealth

Check the health status of the MCP server's connection to backend services.

**Parameters:** None

**Response:**

```json theme={null}
{
  "status": "healthy",
  "message": "OpenSearch connection successful"
}
```

## Client Configuration

### Claude Desktop

Add the following to your Claude Desktop configuration file:

<Tabs>
  <Tab title="macOS">
    Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "govworx": {
          "command": "npx",
          "args": ["-y", "mcp-remote", "https://mcp.govworx.net/sse"],
          "env": {
            "AUTHORIZATION": "Bearer YOUR_API_TOKEN"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Windows">
    Edit `%APPDATA%\Claude\claude_desktop_config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "govworx": {
          "command": "npx",
          "args": ["-y", "mcp-remote", "https://mcp.govworx.net/sse"],
          "env": {
            "AUTHORIZATION": "Bearer YOUR_API_TOKEN"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

### Cursor

Configure MCP in Cursor settings under **Settings > MCP Servers**:

```json theme={null}
{
  "govworx": {
    "url": "https://mcp.govworx.net/sse",
    "headers": {
      "Authorization": "Bearer YOUR_API_TOKEN"
    }
  }
}
```

### MCP Inspector (Testing)

Use the MCP Inspector to test your connection:

```bash theme={null}
npx @modelcontextprotocol/inspector
```

Then connect to `https://mcp.govworx.net/sse` with your Authorization header.

## Troubleshooting

### Common Issues

**401 Unauthorized**

* Verify your API token is valid and not expired
* Ensure the `Authorization` header format is `Bearer <token>` (with a space)
* Check that your token has the required permissions

**403 Forbidden**

* Your token may lack the required permissions for the requested tool
* Contact your administrator to update token permissions

**Connection Timeout**

* The MCP server endpoint may be unreachable from your network
* Check your firewall settings allow outbound connections to `mcp.govworx.net`

### Verify Token

Test your token with a simple curl command:

```bash theme={null}
curl -v -H "Authorization: Bearer YOUR_API_TOKEN" \
     https://mcp.govworx.net/actuator/health
```

A successful response indicates your token is valid and the server is reachable.

## Data Security

* All connections use TLS encryption and operate under FIPS 140-2 validation
* API tokens are validated against the GovWorx authentication service on every request
* Tenant isolation is enforced - you can only access data within your organization
* All data access is logged for audit purposes
* Resource caching uses security-aware keys that include your tenant and user context