suade-fire-mcp

An MCP server that exposes the FIRE data standard so a data engineering team's own AI assistant can look up fields, validate draft records, and get mapping suggestions while mapping an internal data format onto FIRE.

It reads a separate SuadeLabs/fire checkout's schemas/, extensions/, documentation/ and examples/ directly from disk at runtime -- no build step, no network access. This repo and FIRE are independent: clone them separately, and pin the FIRE checkout to a release tag (e.g. git checkout v26.07) if you want a specific version of the standard rather than whatever master currently holds.

Install

You need both repos on disk:

git clone https://github.com/SuadeLabs/fire.git
git clone https://github.com/SuadeLabs/suade-fire-mcp.git
cd suade-fire-mcp
pip install -e .

For local development (running the MCP inspector, tests):

pip install -e ".[dev]"

Related MCP server: Fireberry CRM MCP Server

Run

Point FIRE_REPO_ROOT at your FIRE clone -- this is required, since the server has no FIRE checkout of its own to fall back to:

export FIRE_REPO_ROOT=/path/to/your/clone/of/fire
fire-mcp
# or
python -m fire_mcp.server

This serves over stdio by default. Point an MCP client at it, for example a mcp.json/client config entry like:

{
  "mcpServers": {
    "fire": {
      "command": "fire-mcp",
      "env": { "FIRE_REPO_ROOT": "/path/to/your/clone/of/fire" }
    }
  }
}

Remote / hosted

This serves over stdio by default (a local subprocess, for clients like Claude Code that launch it themselves). For clients that only speak to a server over HTTPS -- claude.ai's chat interface, Claude Desktop's remote connectors -- run it with the Streamable HTTP transport instead, over FIRE_MCP_TRANSPORT=streamable-http.

Run the published image (a FIRE checkout is baked in at build time, pinned to a release tag -- no separate clone needed):

docker run -p 8000:8000 \
  -e FIRE_MCP_ALLOWED_HOSTS=your-host.example.com \
  -e FIRE_MCP_ALLOWED_ORIGINS=https://your-host.example.com \
  ghcr.io/suadelabs/suade-fire-mcp:latest

FIRE_MCP_ALLOWED_HOSTS / FIRE_MCP_ALLOWED_ORIGINS are required -- without them every request from a real hostname is rejected with 421 Misdirected Request (DNS-rebinding protection in the MCP SDK). Set them to wherever this is actually reachable.

Build your own image, optionally pinned to a different FIRE tag:

docker build --build-arg FIRE_VERSION=v26.07 -t suade-fire-mcp .

This is a normal public image -- running your own copy anywhere needs nothing from Suade beyond the image itself, the same way cloning FIRE needs nothing beyond the repo.

Connecting from Claude: the server is authless and every tool is read-only, so there is nothing to sign in to. Once a URL is reachable:

• claude.ai / Claude Desktop / mobile: Customize -> Connectors -> Add custom connector, and enter https://<your-host>/mcp. On Team and Enterprise plans an Owner adds it once for the whole organization.

• Claude Code: claude mcp add --transport http fire https://<your-host>/mcp

Operating a hosted instance:

• The HTTP transport is stateless (no MCP sessions), so machines can restart or scale out without breaking anyone's conversation. GET /health returns {"status": "ok"} for load balancer checks.

• Claude's requests come from Anthropic's egress range 160.79.104.0/21. Don't block it at a firewall/WAF, and don't rate-limit per IP -- every claude.ai user shares those addresses.

• Tool arguments (including draft records passed to validate_record / validate_batch) are never stored, and are only logged at DEBUG level. Don't run a public instance with debug logging on.

• Tool results are sized to stay inside Claude's limits (~150k characters on claude.ai, 25k tokens by default in Claude Code): list_fields returns per-field summaries, with enum values and docs available one field at a time through get_field. search_fields is capped at 50 results, and validate_batch at 1000 records per call.

What it exposes

Resources:

• fire://schemas/{entity} -- an entity's schema, with all $refs resolved inline

• fire://properties/{field} -- the markdown documentation for one field

• fire://examples/{name} -- a worked example payload

• fire://extensions/{entity} -- an entity's jurisdiction-specific extension fields, if any

Tools (all read-only):

• list_entities -- every FIRE entity with a short description

• list_fields(entity) -- summary of every field on an entity, flagged required / enum

• search_fields(query, limit=10) -- fuzzy search over field names, descriptions and enum values (max 50 results)

• get_field(entity, field) -- full detail on one field, including enum values and docs

• get_enum_definitions(entity, field) -- the prose definition of each value of an enum field

• get_examples(name=None) -- list the worked example payloads, or fetch one by name

• validate_record(entity, record, jurisdiction=None, strict=False) -- validate a JSON record against a FIRE schema; returns {"valid": bool, "issues": [...]}

• validate_batch(records, jurisdiction=None, strict=False) -- validate up to 1000 {"entity", "record"} pairs, plus cross-record *_id reference checks

• suggest_mapping(entity, source_fields, sample_values=None) -- ranked, non-authoritative mapping candidates for a list of your own field names; returns {"candidates": [...], "basis": "..."}, where basis explains what the scores mean

Disclaimer

This is an open-source, AI-assisted tool, provided as-is under the Apache 2.0 license, with no warranty, SLA or support commitment. Use it at your own risk.

• Schemas, field definitions, examples and validation come straight from the published FIRE standard at the pinned release. They are only as current as that release.

• Mapping suggestions are not advice. suggest_mapping ranks candidates by how similar field names look, not by what the fields mean. The AI assistant using this server can also misread or misapply any result. Check every mapping against the FIRE field definitions before relying on it, and don't treat anything this server or an assistant says as a Suade recommendation for regulatory reporting.

• Nothing you send is stored. Tool arguments, including records passed to the validation tools, are not persisted, and the hosted instance does not log them.

License

Apache 2.0 -- see LICENSE, matching FIRE's own license.