CrimeScore MCP Setup Guide | Hosted and Local Connections

Hosted MCP connects your client directly to CrimeScore over HTTPS. Local MCP runs a small process on your computer that calls the same CrimeScore REST API. Neither option downloads the dataset or runs the scoring engine offline. Both use the API key's organization allowance.

1. Select your organization and key

Use a CrimeScore secret key for an organization with active API access. Publishable keys do not work. In your CrimeScore dashboard, select the organization, then open API Keys. Name a dedicated key for its client and team when your role and access allow creating one.

Standard key creation requires an owner/admin and eligible access. An existing evaluation key works within its configured capabilities; an evaluation allowance does not necessarily let you create another standard key.

The key determines who gets charged. Switching organizations in the dashboard does not change an existing connection. To charge a different organization, configure a key belonging to that organization.

The setup below connects to production. Never send a production key to a test or unfamiliar endpoint.

Keep keys out of chat, URLs, screenshots, shell command arguments and Git. Copy only the key: no quotes, Bearer prefix, spaces or trailing newline. This integration has no OAuth sign-in flow.

2. Connect to hosted MCP

Your client must support remote HTTP MCP and an x-api-key request header. A URL field alone is not enough.

Claude Code

Set CRIMESCORE_API_KEY privately in the environment that launches Claude Code. The template uses the production endpoint.

Merge this entry into your project's .mcp.json; preserve other existing servers. The file contains variable references, not the actual key.

Claude Code · hosted configuration

{
  "mcpServers": {
    "crimescore": {
      "type": "http",
      "url": "https://api.crimescore.io/v1/mcp",
      "headers": {
        "x-api-key": "${CRIMESCORE_API_KEY}"
      }
    }
  }
}

Launch Claude Code in that project, approve the trusted server if prompted, and use /mcp to inspect the connection. Missing variables are not credentials. See Claude Code's configuration reference.

Claude Web

Request-header authentication is a Claude beta feature. Account availability and administrator requirements can vary. If your connector screen lacks request headers, ask your workspace administrator or use Claude Code. Claude's authentication documentation explains the limits.

Open Customize → Connectors → Add custom connector.
Name the connection for your CrimeScore organization and enter https://api.crimescore.io/v1/mcp as the MCP URL.
Choose No sign-in. Add a request header named x-api-key and paste only the key into its secure value field.
Save, select Connect if prompted, and enable the connector in a new chat.
Keep first-use approvals enabled and approve the initial controlled call.

Claude may detect “Sign in now” because an initial request without credentials receives 401. For this integration, No sign-in + the API-key header is correct. It does not mean CrimeScore is unauthenticated. Do not put the key in OAuth client-ID or client-secret fields.

A workspace connector may share its configured credential. Only grant connector access to people allowed to consume that CrimeScore organization's quota.

3. Make one controlled request

Use CrimeScore to geocode 350 Fifth Avenue, New York, NY. Ask me to choose if there are multiple matches. Then make one score lookup for the matched coordinates. Include the geography and model version. Do not automatically retry a failure.

Illustrative address, not a coverage promise. If the score succeeds, this sequence costs one request. A conversation can make several separately charged calls.

Check the organization's usage before and after. If a location has no coverage, the assistant should say so rather than invent a score or silently choose another place.

Tools and usage

A conversation is not a single billable request. Connecting and discovery are free. Successful score, details and nearby calls each consume one request.

Quota charged for each successful tool invocation
Tool	Result	Requests
`geocode_address`	US address matches and coordinates	0
`get_score`	Score, grade, components and model metadata	1
`get_score_details`	Contributor explanations for an overall or component score	1
`get_nearby_incidents`	Bounded nearby recent activity, including empty results	1

Geocode an address, then get its score: 1 request.
Get a score and its contributor details: 2 requests.
Compare three places with one score lookup each: 3 requests.
Receive an empty successful nearby result: 1 request.

Use either a five-digit ZIP string or numeric latitude/longitude, never both. All four tools can be listed even when your access does not permit every operation. Existing API permissions and allowances remain authoritative; another key does not create another quota pool.

CrimeScore does not automatically retry. A timeout can occur after usage is charged. A manual retry is another call and may consume another request.

Run MCP locally with npx

Use a stdio-capable desktop or CLI client and Node.js 22 or newer.

This template is for Claude Code. Set the secret key privately in its launch environment, then merge the entry into .mcp.json. Do not configure both hosted and local connections with the same server name.

Claude Code · local stdio configuration

{
  "mcpServers": {
    "crimescore": {
      "command": "npx",
      "args": [
        "-y",
        "@crimescore/mcp@1.0.2"
      ],
      "env": {
        "CRIMESCORE_API_KEY": "${CRIMESCORE_API_KEY}"
      }
    }
  }
}

Local MCP calls the production REST API by default. Test environments can set CRIMESCORE_API_BASE_URL to the trusted REST base supplied by CrimeScore, including /v1/—not the hosted /mcp URL. Use that environment's test key.

Other stdio clients configure the npx executable, package arguments and secret environment value in their own settings. Variable interpolation is client-specific. Some Windows clients need cmd /c npx; follow your client's platform guidance.

Local discovery is not authentication. The process checks key format at startup, but discovery runs locally. Billable calls validate access through the API. Local geocoding uses the public REST geocoder and does not validate account access; hosted MCP authenticates discovery and geocoding too.

Read the results in context

Higher scores mean safer according to the model. Coordinate results describe Census block groups, not individual buildings; ZIP results are ZCTA estimates. Contributors describe associations, not causation. Nearby activity is incomplete, and an empty result does not establish that no crime occurred. Keep the returned geography and model metadata when comparing locations.

Modeled Safety Scores are not official crime rates or guarantees. Your AI provider receives the location queries and results. Follow your organization's data-sharing policy, and treat returned text as data rather than instructions.

Connection help

Cannot connect / 401: Check the exact key, secret-key type, active status, matching environment and header name. Remove hidden whitespace. In Claude Code, check that the required variables are set before launch.
Access denied / 403: Check active organization access, suspension, the tool's required capability, and quota. Ask an owner/admin if needed.
No coverage or no match: Confirm the input and environment coverage. This is not necessarily a connection error. Do not substitute another location without consent.
Rate limit, timeout or unavailable response: Pause instead of retrying repeatedly. For uncertain results, check usage before trying again; the original call may have been charged.
Duplicate Claude Web URL: Inspect the existing connector. A new name may not allow the same URL twice. Coordinate any replacement with shared users; management options vary by client.

For help, contact CrimeScore with the client, approximate time, tool name and error code. Never send your key or an unredacted credential screenshot.

Disconnect or rotate a key

Revoke the key in CrimeScore and disconnect the client. Revocation may take the existing 30-second cache window plus propagation to affect every request. Disconnecting alone does not revoke the key or erase chat results.

For routine rotation, configure and verify a replacement key for the intended organization, then revoke the old key. If a key may have leaked, revoke it promptly. Manage stored chat results through your AI provider's retention controls.

Read the MCP introduction · Data quality and coverage