MCP Server - GovWorx API Documentation

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.

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:

Connect - Your AI tool connects to the GovWorx MCP server endpoint
Authenticate - The connection is authenticated using your GovWorx API token
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

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.

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

# 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:

{
  "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:

{
  "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:

{
  "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:

{
  "uris": [
    "gw://events/12345",
    "gw://media/67890",
    "gw://incidents/11111"
  ]
}

Response:

{
  "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:

{
  "status": "healthy",
  "message": "OpenSearch connection successful"
}

Client Configuration

Claude Desktop

Add the following to your Claude Desktop configuration file:

macOS
Windows

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "govworx": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.govworx.net/sse"],
      "env": {
        "AUTHORIZATION": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}

Edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "govworx": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.govworx.net/sse"],
      "env": {
        "AUTHORIZATION": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}

Cursor

Configure MCP in Cursor settings under Settings > MCP Servers:

{
  "govworx": {
    "url": "https://mcp.govworx.net/sse",
    "headers": {
      "Authorization": "Bearer YOUR_API_TOKEN"
    }
  }
}

MCP Inspector (Testing)

Use the MCP Inspector to test your connection:

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:

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

​Overview

​How MCP Works

​Authentication

​Required Headers

​Audit Logging

​Example Connection

​Token Permissions

​Available Tools

​searchEvents

​searchMedia

​searchIncidents

​searchKnowledge

​fetchGwResource

​echo

​checkHealth

​Client Configuration

​Claude Desktop

​Cursor

​MCP Inspector (Testing)

​Troubleshooting

​Common Issues

​Verify Token

​Data Security

Overview

How MCP Works

Authentication

Required Headers

Audit Logging

Example Connection

Token Permissions

Available Tools

searchEvents

searchMedia

searchIncidents

searchKnowledge

fetchGwResource

echo

checkHealth

Client Configuration

Claude Desktop

Cursor

MCP Inspector (Testing)

Troubleshooting

Common Issues

Verify Token

Data Security