Skip to main content
Glama

occ-gis-mcp

An MCP (Model Context Protocol) server that gives AI assistants (like Claude, GitHub Copilot, or any MCP-compatible client) access to public GIS datasets from the Oklahoma Corporation Commission's open data hub: https://gisdata-occokc.opendata.arcgis.com/

No coding experience required to set this up. Follow the steps below in order.

What is this, in plain terms?

MCP ("Model Context Protocol") is a standard way for AI chat tools to call small programs ("servers") that fetch live data. This repo is one of those servers. Once it's set up, you can ask your AI assistant things like:

  • "List the datasets available from the OCC GIS hub"

  • "Find all active oil wells in Oklahoma County"

  • "Show me the fields available on the PST Tanks layer"

and the assistant will use this server to fetch real, live answers instead of guessing.

Related MCP server: mcp-arcgis-houston

Step 1 — Install Node.js

This server runs on Node.js. If you don't already have it:

  1. Go to https://nodejs.org

  2. Download the LTS (Long Term Support) version for your operating system.

  3. Run the installer, accepting the defaults.

  4. Confirm it worked by opening a terminal (PowerShell on Windows, Terminal on Mac/Linux) and running:

    node -v
    npm -v

    Both should print a version number (e.g. v20.11.0). If you see an error, restart your terminal/computer and try again.

Step 2 — Download this project

Option A: Using Git (recommended if you have it)

git clone https://github.com/MSPFE2019/occ-gis-mcp.git
cd occ-gis-mcp

Option B: Without Git

  1. Go to https://github.com/MSPFE2019/occ-gis-mcp

  2. Click the green Code button → Download ZIP

  3. Unzip it somewhere you'll remember (e.g. your Documents folder)

  4. Open a terminal and cd into that unzipped folder, for example:

    cd "C:\Users\YourName\Documents\occ-gis-mcp"

Step 3 — Install dependencies

From inside the project folder, run:

npm install

This downloads the small libraries the server needs. You only need to do this once (and again any time the code changes).

Step 4 — Test that it runs

There are two ways to run this server — pick based on where you'll use it:

  • index.js — for local desktop tools (Claude Desktop, VS Code/Copilot Chat).

  • http.js — for remote/cloud tools like Copilot Studio (see the dedicated section below).

Try the local one first:

node index.js

Nothing will print — that's expected! MCP servers talk over a silent input/output channel and just wait for a client to connect. Press Ctrl+C to stop it.

For a more visual test, use the official MCP Inspector, which opens a browser page where you can click buttons and see live results:

npx @modelcontextprotocol/inspector node index.js

This opens a local webpage. Click Connect, then List Tools, then try running list_datasets with no arguments — you should see a list of real datasets come back as JSON. If that works, the server is working correctly.

Step 5 — Connect it to your AI assistant

MCP servers are configured once inside your AI client's settings. Pick the guide that matches your tool:

Claude Desktop

  1. Open Claude Desktop → Settings → Developer → Edit Config (this opens claude_desktop_config.json in a text editor).

  2. Add an entry like this (replace the path with your actual project folder, using double backslashes \\ on Windows):

    {
      "mcpServers": {
        "occ-gis": {
          "command": "node",
          "args": ["C:\\Users\\YourName\\Documents\\occ-gis-mcp\\index.js"]
        }
      }
    }
  3. Save the file and fully restart Claude Desktop.

  4. Ask it: "What OCC GIS datasets are available?"

VS Code (GitHub Copilot Chat) or other MCP-aware editors

  1. Open (or create) an mcp.json file in your MCP settings (in VS Code: Command Palette → "MCP: Open User Configuration", or add it to your workspace's .vscode/mcp.json).

  2. Add the same mcpServers block shown above.

  3. Reload the window and the new tools will appear when you chat with Copilot.

Any other MCP client

Any client that supports the MCP standard accepts the same shape of config: a command (node) and args (the full path to index.js). Consult your client's documentation for where that config file lives.

Available tools

Once connected, your assistant can call these:

Tool

What it does

list_datasets

Search/list the datasets on the hub (wells, tanks, etc.). Optional free-text query.

get_dataset

Full details for one dataset by title, including download links (CSV, GeoJSON, Shapefile, KML, File Geodatabase) and its live ArcGIS service URL.

get_layer_metadata

Field names, geometry type, and extent for a given ArcGIS layer URL.

query_layer

Run attribute (where) and/or spatial queries against a layer and get back matching records.

Customizing for a different ArcGIS Hub site

This server isn't limited to the OCC's data — it works with any ArcGIS Hub site that exposes a DCAT-US catalog feed (most public ArcGIS Hub sites do). To point it at a different site, open server.js and change this line near the top:

const HUB_BASE = "https://gisdata-occokc.opendata.arcgis.com";

to your target site's base URL, then re-run the server. Everything else (tool names, query logic) works the same way.

Connecting to Microsoft Copilot Studio

Copilot Studio doesn't run this server for you — it needs to reach it over the internet as an HTTPS URL. That's what http.js is for (as opposed to index.js, which is only for local tools like Claude Desktop). There are two parts: (A) put the server somewhere reachable on the internet, then (B) register it in Copilot Studio.

A. Deploy the HTTP server somewhere public

Pick whichever is easiest for you — all of them run the same command: npm install then npm run start:http.

Easiest for beginners — Azure App Service (or Azure Container Apps)

  1. Push this repo to your own GitHub account (already done if you're reading this from your fork/copy).

  2. In the Azure Portal, create a Web App → Runtime stack: Node 20 LTS → deploy from your GitHub repo (Azure sets up CI/CD for you).

  3. Under Configuration → Startup Command, set:

    node http.js
  4. Once deployed, Azure gives you a URL like https://occ-gis-mcp.azurewebsites.net. Your MCP endpoint is that URL plus /mcp, e.g. https://occ-gis-mcp.azurewebsites.net/mcp.

Also simple — Render, Railway, or Fly.io Any of these can deploy a Node.js repo from GitHub in a few clicks:

  • Build command: npm install

  • Start command: npm run start:http

  • They'll give you a public https://... URL — again, append /mcp.

Local testing only (not for production)

npm install
npm run start:http

This starts the server at http://localhost:3000/mcp. To test whether Copilot Studio (a cloud service) can reach a server on your own machine, you'd need a tunnel tool like ngrok (ngrok http 3000), which gives you a temporary public HTTPS URL. This is fine for a quick demo, not for real/ongoing use.

B. Register it in Copilot Studio

  1. Open your agent in Copilot Studio → go to Tools (or Actions) → Add a toolNew toolModel Context Protocol.

  2. Give it a name (e.g. "OCC GIS Data") and paste your server's HTTPS URL including /mcp, e.g. https://occ-gis-mcp.azurewebsites.net/mcp.

  3. Choose No authentication (this server is read-only and doesn't require credentials) unless you've added your own auth layer in front of it.

  4. Save. Copilot Studio will call the server and automatically discover the four tools (list_datasets, get_dataset, get_layer_metadata, query_layer) along with their descriptions — no manual schema entry needed.

  5. Test it in the Copilot Studio test chat pane: ask "What OCC GIS datasets are available?" or "Find active wells in Oklahoma County."

Available tools

Once connected, your assistant can call these:

Tool

What it does

list_datasets

Search/list the datasets on the hub (wells, tanks, etc.). Optional free-text query.

get_dataset

Full details for one dataset by title, including download links (CSV, GeoJSON, Shapefile, KML, File Geodatabase) and its live ArcGIS service URL.

get_layer_metadata

Field names, geometry type, and extent for a given ArcGIS layer URL.

query_layer

Run attribute (where) and/or spatial queries against a layer and get back matching records.

Troubleshooting

  • node: command not found — Node.js isn't installed or your terminal needs restarting after installation. Redo Step 1.

  • Inspector/tool call errors mentioning network/fetch — check your internet connection; the server calls the live ArcGIS Hub API on every request.

  • Assistant doesn't see the new tools — double check the file path (local) or URL (Copilot Studio) is correct, and that you fully restarted/reconnected the client.

  • Copilot Studio says it can't connect — make sure you registered the URL ending in /mcp (not just the bare domain), that the deployment is actually running, and that it's reachable over plain HTTPS (no VPN/firewall blocking it).

Notes

  • The dataset list is pulled live from the hub's DCAT-US catalog feed and cached for 15 minutes to keep things fast.

  • Data is public but subject to the source agency's terms of use (shown in the get_dataset output's license field).

  • http.js runs in stateless mode (a fresh server per request), which keeps hosting simple and is fully compatible with how Copilot Studio calls MCP tools.

Available Tools

4 tools
get_datasetGet OCC GIS dataset detailsA

Get full details for one dataset on the OCC GIS hub by exact or partial title match, including every distribution (ArcGIS REST service URL, CSV/GeoJSON/Shapefile/KML/FileGDB download links), spatial extent, and license text.

ParametersJSON Schema
NameRequiredDescriptionDefault
titleYesDataset title or a distinctive substring of it, e.g. 'RBDMS WELLS' or 'PST Tanks'

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden. It does disclose the returned content and the exact/partial matching behavior, which is useful. However, it does not mention how ambiguous partial matches are handled (e.g., multiple matches, error vs. arbitrary selection), nor any potential side effects or permissions, leaving some behavioral gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that states the action, scope, and key return details without redundancy or filler. Every clause contributes useful information, and it is easily scannable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity (one parameter, no output schema), the description is reasonably complete: it covers purpose, matching behavior, and enumerates the returned information. The only notable omission is clarifying behavior when a partial title matches multiple datasets, but this does not severely undermine usability.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already fully describes the 'title' parameter with examples and the note about distinctive substrings. The tool description adds 'exact or partial title match', but this largely restates the schema's own description. Schema coverage is 100%, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb+resource structure ('Get full details for one dataset on the OCC GIS hub') and clearly enumerates the return contents (distributions, spatial extent, license text). It distinguishes this from sibling tools by focusing on a single dataset found by title, contrasting with list_datasets.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use the tool: when you need full details of one dataset found by exact or partial title match. It does not explicitly name alternatives or state when not to use it, but the context is unambiguous and implies a targeted lookup rather than listing or querying.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_layer_metadataGet ArcGIS layer metadataA

Fetch metadata (fields, geometry type, extent, name, description) for an ArcGIS FeatureServer/MapServer layer URL, such as one returned by list_datasets or get_dataset as 'featureServiceUrl'.

ParametersJSON Schema
NameRequiredDescriptionDefault
layerUrlYesArcGIS REST layer URL, e.g. https://gis.occ.ok.gov/server/rest/services/Hosted/RBDMS_WELLS/FeatureServer/220

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must convey behavioral traits. The verb 'Fetch' implies a read-only operation, and the description lists the returned metadata fields, which is useful. However, it does not disclose error handling, authentication requirements, or any side effects (though likely none). It is adequate but lacks rich behavioral context that might be expected.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that front-loads the action and resource, then lists the metadata fields. It is concise with no fluff, and every word adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple (one parameter, no output schema), and the description covers its purpose, input source, and the fields it returns. It goes beyond the minimum by specifying the expected URL type and provenance. Minor gaps include not describing the response format, but the listed fields effectively convey what is returned.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already fully describes the single parameter 'layerUrl' with a description and example, giving 100% schema coverage. The description adds a small hint about the URL's provenance (from list_datasets/get_dataset) and that it should be a layer endpoint, but this is marginal. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with a specific verb ('Fetch') and resource ('ArcGIS FeatureServer/MapServer layer URL'), enumerating the exact metadata fields returned (fields, geometry type, extent, name, description). It also differentiates from siblings by referencing list_datasets/get_dataset and focusing on metadata, not querying.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides context on when to use the tool: for a layer URL such as one returned by list_datasets or get_dataset as 'featureServiceUrl'. This implies it is the follow-up to those tools. It does not explicitly exclude alternatives like query_layer, but the context is clear enough for an agent to choose it for metadata retrieval.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_datasetsList OCC GIS datasetsA

List/search datasets published on the OCC GIS open data hub (gisdata-occokc.opendata.arcgis.com). Optionally filter with a free-text query matched against title, description, and keywords. Returns each dataset's title, description, landing page, keywords, and (when available) its ArcGIS FeatureServer/MapServer REST URL plus downloadable formats (CSV, GeoJSON, Shapefile, KML, File Geodatabase).

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMax number of results to return (default 25)
queryNoOptional free-text search, e.g. 'wells', 'tanks', 'pipeline'

TDQS

A4.1/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It discloses the data source URL, search matching behavior (title, description, keywords), and return fields, plus the caveat 'when available' for REST URL and formats, offering honest behavioral insight without promising more than the tool likely delivers.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences and front-loads the core purpose. It is somewhat dense with comma-separated return field details, but every element serves a functional purpose and no filler exists.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema is present, so the description adequately enumerates return fields and optional filters. It could mention pagination or default limits, but the limit parameter in the schema already covers that, making this sufficiently complete for a list/search tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema already has 100% coverage for the two parameters. The description adds meaning beyond the schema by specifying that the query is 'matched against title, description, and keywords', which enriches the schema's generic 'Optional free-text search'.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'List/search datasets published on the OCC GIS open data hub', using a specific verb and resource. It clearly distinguishes from siblings like get_dataset (single dataset) and query_layer (feature query) by focusing on dataset listing/searching.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains what the tool does and the optional query filter, but it does not explicitly state when to use this tool over siblings or when to avoid it. Usage is implied by the 'List/search' purpose, but no alternatives or exclusions are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

query_layerQuery an ArcGIS layer's featuresA

Run an attribute and/or spatial query against an ArcGIS FeatureServer/MapServer layer (e.g. OCC well points, tank sites) and return matching feature attributes (and optionally geometry) as JSON. Use get_layer_metadata first to see available fields.

ParametersJSON Schema
NameRequiredDescriptionDefault
whereNoSQL-style attribute filter, e.g. "COUNTY = 'OKLAHOMA'" or "STATUS = 'AC'". Defaults to 1=1 (all rows).
geometryNoOptional spatial filter geometry, e.g. 'xmin,ymin,xmax,ymax' envelope in WGS84 lon/lat.
layerUrlYesArcGIS REST layer URL, e.g. https://gis.occ.ok.gov/server/rest/services/Hosted/RBDMS_WELLS/FeatureServer/220
outFieldsNoComma-separated field names to return, or '*' for all (default).
spatialRelNoSpatial relationship, e.g. esriSpatialRelIntersects (default).
geometryTypeNoGeometry type for the 'geometry' param, e.g. esriGeometryEnvelope (default) or esriGeometryPoint.
orderByFieldsNoComma-separated field(s) to sort by, e.g. 'API_NUMBER ASC'.
returnGeometryNoWhether to include geometry (lat/lon) in results (default false).
resultRecordCountNoMax number of records to return (default 50).

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses the return format (JSON), optional geometry inclusion, and the nature of querying (read-only is implied). It could mention error handling or response size limits, but the 'Use get_layer_metadata first' hint and example layer URLs add useful context beyond minimal.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences long, front-loaded with the action, and every word contributes. It avoids redundancy while including examples and a usage hint, making it both concise and structured for quick scanning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 9 parameters and no output schema, the description covers the essential context: purpose, return type, and a prerequisite action. It does not mention output structure or error handling, but given the interactive schema and sibling context, it is reasonably complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all parameters. The description adds a helpful pointer to get_layer_metadata for field discovery, but does not elaborate on parameter relationships or edge cases. This meets the baseline for high schema coverage without adding substantial extra meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool runs an attribute and/or spatial query against an ArcGIS FeatureServer/MapServer layer and returns matching features as JSON. It uses a specific verb 'Run' and identifies the resource (layer), examples (OCC well points, tank sites), and distinguishes from siblings by explicitly mentioning get_layer_metadata.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit context for when to use this tool (attribute/spatial query) and instructs to use get_layer_metadata first to see available fields, which implies a prerequisite step. It does not explicitly mention when not to use it or compare with list_datasets/get_dataset, but the guidance is clear enough for typical use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv1.0.0
    • First observedget_dataset
    • First observedget_layer_metadata
    • First observedlist_datasets
    • First observedquery_layer

TDQS

A4.4/5.0

Scored across 4 tools

Disambiguation5/5

Each tool has a clearly distinct role: listing/searching datasets, fetching full dataset details, inspecting layer metadata, and querying layer features. There is no overlap that would confuse an agent selecting among them.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern (list_datasets, get_dataset, get_layer_metadata, query_layer), using snake_case throughout and verbs that clearly indicate the action.

Tool Count5/5

Four tools is an appropriate scope for a read-only GIS data discovery and query server. Each tool fills a necessary step in the workflow without redundancy or bloat.

Completeness5/5

The tool surface fully covers the core workflow: discovering datasets, retrieving full metadata, inspecting layer schemas, and querying features. No obvious dead ends exist; even direct data downloads are covered via distribution URLs returned by the get_dataset tool.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • A
    license
    A
    quality
    B
    maintenance
    An MCP server that gives LLM agents typed, cached access to civic open-data portals via Socrata (SODA 2.1 + Discovery API), enabling search, query, profiling, sampling, and CSV export of datasets.
    6
    MIT