Skip to main content
Glama
Texas Flood Knowledge Graph MCP Server

Texas Flood Knowledge Graph MCP Server

Texas Flood Knowledge Graph MCP Server

An MCP server that gives AI agents direct, read-only SPARQL access to the Texas Flood Systems Knowledge Graph, an integrated graph linking flood hazards to community vulnerability across Texas counties.

Built for GSA's 2026 MCP Server and AI Agent Hackathon (data track, IBM watsonx Orchestrate + Bob), from the GSA-TTS hackathon template.

This server does not call an external API. The graph is bundled with the server, loaded into an in-memory Oxigraph store at startup, and queried with SPARQL.


What it does

Most MCP servers wrap a REST API with a fixed set of endpoints. This one exposes a knowledge graph instead: an agent can discover the graph's structure, read documented schema and analytical guidance, and write its own SPARQL queries across four publicly-available datasets joined through shared county entities.

Dataset

Content in the graph

NOAA Storm Events

1,540 flood, flash flood, and coastal flood events

FEMA Disaster Declarations

Declarations and 177 per-county designations with program flags (PA, IH, HM, IA)

Census ACS

County demographic, economic, housing, communications, education, and transportation indicators

NWS Watches and Warnings

1,350 county-based flash flood warnings, 2023–2025 (via Iowa Environmental Mesonet)

The graph is grounded in a flood ontology developed through a participatory expert workshop co-hosted with the Natural Hazards Center.

How the data is served: Oxigraph as an in-memory triple store

The MCP server queries an embedded Oxigraph triple store, used through its Python binding, pyoxigraph. There is no separate database server:

  1. At startup, the server loads data/texas_flood2.ttl (108,137 triples, roughly 10 MB of Turtle) into an in-memory Oxigraph store. Loading takes about a second, and the server fails fast if the file is missing or malformed.

  2. On each tool call, the SPARQL query runs directly against that store inside the same process. No network hop and no external service are involved.

  3. The store is read-only in practice. The server only ever runs SELECT and ASK queries against it, and it is rebuilt from the Turtle file on every start, so nothing an agent does can change the data.

This keeps deployment to a single container: the graph ships inside the image, and Oxigraph supports full SPARQL 1.1 querying without a database to install or operate. The trade-offs are that the whole graph lives in memory (well under 1 GB here), that each cold start reloads it, and that updating the data means rebuilding the image. A larger or frequently updated graph would move to a hosted triple store, such as Amazon Neptune or GraphDB, with the MCP tools unchanged apart from where queries are sent.

Example questions the agent answers:

  • Which counties are most vulnerable to flooding? (separate rankings for each vulnerability indicator)

  • Which FEMA-designated counties have the highest poverty rates?

  • How many counties received both NWS flood warnings and FEMA disaster declarations?


Related MCP server: local-dfw-mcp

Tools, resources, and prompt

Name

Type

Purpose

kg_get_schema

Tool

Returns the schema: classes, properties, indicator formulas, analytical constructs, common graph paths

kg_get_query_guidelines

Tool

Returns analyst guidelines: SPARQL rules, county reporting, hallucination prevention

kg_list_classes

Tool

Lists classes with instance counts and labels

kg_list_predicates_for_class

Tool

Lists the properties used by a class

kg_sample_instances

Tool

Returns example instances with all their properties (up to 50)

kg_run_sparql

Tool

Runs read-only SELECT or ASK queries; 200-row cap with a truncation flag

kg://schema, kg://query-guidelines

Resources

Same content as the two get tools, for clients that read MCP resources

flood_kg_analyst

Prompt

The guidelines packaged as an analyst system prompt

The schema and guidelines are also exposed as tools because some clients, including watsonx Orchestrate and LangChain's MCP adapter, load only tools.

Safety

  • Read-only. Update queries are rejected by the store; CONSTRUCT and DESCRIBE are rejected by result type.

  • No SPARQL injection. Class URIs supplied by agents are validated as IRIs and bound as query parameters, never inserted into query text.

  • Bounded results. SELECT results are capped at 200 rows, and errors return a message with a hint rather than a stack trace.

  • Logging. Each tool call is logged, including the SPARQL text and row count, so every answer can be traced to the query that produced it.


Architecture

User → watsonx Orchestrate agent → MCP (streamable HTTP) → IBM Code Engine
                                                            └─ FastMCP server
                                                               └─ Oxigraph in-memory triple store
                                                                  (pyoxigraph, loaded from
                                                                   data/texas_flood2.ttl)

Path

Contents

src/flood_kg_mcp/

Server: tools, resources, prompt, store loading

data/

The graph (texas_flood2.ttl), schema, and analyst guidelines

deploy/ibm/agent/flood_agent.yaml

The Orchestrate agent definition (instructions, guidelines, tools)

eval/phoenix/

Evaluation harness and gold dataset

tests/

48 tests, run through FastMCP's in-memory client


Running locally

Requires uv.

uv sync
uv run python main.py          # stdio mode, for local MCP clients
uv sync --group dev
uv run pytest tests/ -v
uv run ruff check . && uv run ruff format --check .

Deploying

The server runs as a container on IBM Code Engine (Dockerfile; dependencies pinned to uv.lock) and serves MCP at /mcp. To register it with watsonx Orchestrate and load the agent:

orchestrate toolkits add --kind mcp --name <toolkit-name> \
  --description "Texas Flood Knowledge Graph" \
  --url "https://<your-app-url>/mcp" --transport "streamable_http" --tools "*"
orchestrate agents import -f deploy/ibm/agent/flood_agent.yaml

The agent file refers to tools by toolkit name, so update its tools: entries if you use a different name.


Evaluation

A 10-question gold dataset (eval/phoenix/datasets/flood-eval-0/evaluation.xml) covers counts, cross-dataset joins, rates, a multi-indicator construct, a derived property, a refusal case, and an out-of-scope case. Every gold answer was produced by running SPARQL directly against the graph; the queries are in eval/phoenix/scratch/.

watsonx Orchestrate agent: 10/10. Each question was asked in a fresh chat and checked against the gold answer and the server logs.

Three findings from that testing:

  1. The model fabricated results despite correct queries. For two questions, the agent wrote the right SPARQL and received the right rows, then presented invented ones. A guideline requiring it to report only rows returned by kg_run_sparql fixed this.

  2. The model built a composite score the schema forbids. A guideline and instruction to decline composite indexes and offer individual indicators fixed this.

  3. Earlier answers leak into later ones. In a continuing chat, the agent reused a previous result instead of applying a new filter. Evaluation questions should each run in a fresh chat.

Building the gold answers also surfaced and fixed several schema errors (program flags documented on the wrong class, an undercounted elderly population, NWS coverage overstated) that would have misled any agent.

An automated harness using Arize Phoenix with LLM judges is in eval/phoenix/. It compares a minimal prompt with one that includes the schema up front, across multiple models. See eval/phoenix/README.md.


Known limitations

  • NWS data contains flash flood warnings (FF) only; flood warnings (FA) were lost in the graph build.

  • One FEMA declaration title has a trailing space ("HURRICANE BERYL "), so exact title matches fail.

  • The broadband access rate divides by households with internet access, which leaves little variation between counties.

  • Indicators for very small counties (such as Loving and Kenedy) are based on few residents and can be extreme.

  • SPARQL queries have no execution timeout.

  • The deployed endpoint has no authentication, matching the hackathon's public-data setup.

License

MIT. See SECURITY.md for the vulnerability disclosure policy.

Tool Schema Changelog

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

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables searching and querying Texas open data from data.texas.gov via the Socrata SoQL API, supporting dataset discovery, filtering, and metadata retrieval without an API key.
      159 npm
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to answer DFW civic and property questions using official data sources without API keys.
      9
      76 npm
      2
      Apache 2.0
    • A
      license
      A
      quality
      C
      maintenance
      Provides AI assistants with plain-English access to official Houston-area public data including weather alerts and school ratings, no API keys required.
      3
      1
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      A unified Model Context Protocol server for Houston-area civic, transit, and flood data, joining incompatible public data systems behind workflow-oriented tools. It enables AI assistants to answer questions like 'is my route flooding right now?' by integrating sources such as TranStar, HCFWS, and the GIS hub.
      MIT