FairCom MCP Server
With the FairCom MCP Server, AI assistants can safely interact with FairCom databases:
Data Exploration & Querying: Discover tables and schemas (list tables, describe columns/indexes), run read-only paginated SQL queries.
Safe Write Operations: Execute INSERT/UPDATE/DELETE only after mandatory dry-run preview and explicit confirmation; same safety model applies to connector and integration table management.
Connector & Service Management: List, describe, create, alter, and delete FairCom Edge input/output connectors; validate payloads and manage services.
Integration Tables & Code Packages: Full lifecycle management for integration tables and code packages (e.g., JavaScript transforms) with safety controls.
Operational Observability: Health checks, runtime status, Prometheus metrics, audit logs, and capability summaries.
Utility & Discovery: Usage contract retrieval, session management, and policy-based access control (allow/deny lists, policy presets).
Allows GitHub Copilot to interact with FairCom databases for querying, schema discovery, and safe write operations.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@FairCom MCP Server List all tables in the database"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP Server (FairCom Proof of Concept)
Independent proof of concept: This project was created independently by Todd Stoffel for experimentation with FairCom products. It is not an official FairCom project and is not affiliated with, sponsored by, endorsed by, or supported by FairCom.
Developers and maintainers: useBUILD.md for build, packaging, and release instructions. This README is product and usage focused.
Connect AI assistants and LLMs to data backends with explicit write controls, Linux packaging, and operational tooling. The proof-of-concept adapter included here targets FairCom databases and their JSON APIs.
Proof-of-Concept Scope
The MCP transport, session handling, policy controls, write-confirmation workflow, rate limiting, and observability are not inherently dependent on FairCom software. FairCom is the reference backend used to demonstrate those capabilities in this repository.
Adapting the project to another database or service primarily means replacing the backend adapter and its tool-specific mappings while retaining the MCP server and operational layers. The implementation as currently distributed includes a FairCom adapter, so its FairCom-specific tools require access to the corresponding FairCom APIs.
Current release: v${PROJECT_VERSION}. The install examples and release automation in this repository are aligned to this version.
Set the release version once per shell session so the examples stay aligned with the package source of truth:
PROJECT_VERSION="$(make version)"┌─────────────────────────────────────────────────────────────┐
│ Your AI Assistant (Claude, Copilot, etc.) │
└────────────────────┬────────────────────────────────────────┘
│ MCP Protocol
│ (HTTP + JSON-RPC)
┌────────────────────▼────────────────────────────────────────┐
│ FairCom MCP Server │
│ • Session management │
│ • Write safety enforcement (confirm_write=true) │
│ • Tool exposure control │
│ • Rate limiting, observability │
└────────────────────┬────────────────────────────────────────┘
│ FairCom JSON API
│ (HTTP REST)
┌────────────────────▼────────────────────────────────────────┐
│ FairCom Database │
│ (Edge, DB, RTG, ISAM, MQ) │
└─────────────────────────────────────────────────────────────┘Why FairCom MCP?
Open source: Apache 2.0
Operationally ready: systemd service, log rotation, health checks
Safe by default: explicit write confirmation and tool allowlisting
Broad compatibility: works with Edge, DB, RTG, ISAM, and MQ
MCP-focused: intended for Claude, Copilot, and local LLM workflows
Related MCP server: UOFastMCP
Safe Write Workflow
Use the write controls to make destructive operations predictable and reviewable.
Start with a read-only query to confirm the target data.
Preview writes with
dry_run=Truebefore applying anything.Review the preview output, especially the scoped
WHEREclause and row impact.Apply the change only with
confirm_write=Trueanddry_run=False.Check the audit trail and metrics endpoints after execution.
# Preview a deletion without changing data
preview = faircom_mcp.sql_execute(
"DELETE FROM staging_orders WHERE created_at < '2026-01-01'",
dry_run=True,
)
if preview["would_succeed"]:
# Only after review, run the real write
faircom_mcp.sql_execute(
"DELETE FROM staging_orders WHERE created_at < '2026-01-01'",
confirm_write=True,
dry_run=False,
)For production use, prefer an operator or admin policy bundle and keep dry-runs in the loop for high-risk statements such as DELETE, UPDATE, or DROP.
Use Cases
1. Business Intelligence & Reporting
Let users ask natural-language questions about FairCom data.
Example: "What were our top 5 products by revenue last quarter?"
The AI assistant translates this to SQL, queries FairCom, and summarizes results with visualizations.
# FairCom MCP exposes:
# sql_query(statement, params?) → fetch data
# list_tables(name_like?) → discover schema
# list_table_columns(table_name) → understand structure2. Data Integration & ETL
Automate data pipelines that read/write to FairCom.
Example: Sync customer data from SaaS → FairCom using AI-guided transformations.
# The AI assistant can:
# 1. List available tables (list_tables)
# 2. Inspect target schema (describe_table)
# 3. Execute transformations (sql_execute with confirm_write=true)
# 4. Validate results (sql_query to spot-check)3. Operational Analytics
Real-time status monitoring and anomaly detection.
Example: "Show me any orders with payment processing delays."
# FairCom MCP provides:
# - /metrics → Prometheus-compatible metrics
# - /diagnostics → System health
# - sql_query → Run diagnostic queries
# Combine for full observability loop4. Domain-Specific AI Chatbots
Build internal tools (CRM, inventory, compliance).
Example: Chatbot for warehouse staff to check inventory levels, process returns.
# Sandbox the chatbot with:
# FAIRCOM_TOOL_GROUP_ALLOWLIST=metadata,query
# (write tools disabled for read-only workflows)
#
# FAIRCOM_SQL_DENYLIST=DELETE,DROP
# (prevent destructive operations)Quick Start (5 Minutes)
Option 1: Docker (Fastest)
# Start FairCom MCP pointing to your FairCom instance
docker run -d --name faircom-mcp \
-p 8000:8000 \
-e FAIRCOM_API_BASE_URL=http://faircom-host:8080 \
-e FAIRCOM_API_USERNAME=ADMIN \
-e FAIRCOM_API_PASSWORD=ADMIN \
faircomteam/faircom-mcp:latest --transport httpIf FairCom is running on your local host machine, use:
-e FAIRCOM_API_BASE_URL=http://host.docker.internal:8080Option 2: Linux Package (Production)
Debian/Ubuntu:
sudo apt-get install -y "./faircom-mcp_${PROJECT_VERSION}_all.deb"
sudo systemctl enable --now faircom-mcpRHEL/Rocky/AlmaLinux:
sudo dnf install -y "./faircom-mcp-${PROJECT_VERSION}-1.noarch.rpm"
sudo systemctl enable --now faircom-mcpVerify it's running:
# Health check
curl -fsS http://127.0.0.1:8000/health
# Output: {"status":"ok"}
# List available tables
curl -i -X POST http://127.0.0.1:8000/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
--data '{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2025-03-26",
"capabilities": {},
"clientInfo": {"name": "test", "version": "1.0"}
}
}' | head -20Docker Hub Usage
The image repository maintained for this proof of concept is:
faircomteam/faircom-mcp
Recommended tag usage:
latest: Recommended default tag for standard usersv*tags (for examplevX.Y.Z): Immutable release tags for production pinning
Pull examples:
# Default current image
docker pull faircomteam/faircom-mcp:latest
# Pin to an immutable release for production
docker pull faircomteam/faircom-mcp:vX.Y.ZRun example (recommended default):
docker run -d --name faircom-mcp \
-p 8000:8000 \
-e FAIRCOM_API_BASE_URL=http://faircom-host:8080 \
-e FAIRCOM_API_USERNAME=ADMIN \
-e FAIRCOM_API_PASSWORD=ADMIN \
faircomteam/faircom-mcp:latest --transport httpNotes:
Use
latestfor normal usage and quick evaluation.Use release tag pins (
v*) only when you need immutable version locking.latestandv*tags are published together from the same release tag workflow.
Tutorial: Query Your First Table
Let's query FairCom using Claude or a local LLM via FairCom MCP.
Step 1: Initialize MCP Session
curl -i -X POST http://127.0.0.1:8000/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
--data '{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2025-03-26",
"capabilities": {},
"clientInfo": {"name": "my-client", "version": "1.0"}
}
}' 2>&1 | grep -i "mcp-session-id"
# Save the session ID from the response, e.g.: abc123
SESSION_ID="abc123"Step 2: List Tables
curl -X POST http://127.0.0.1:8000/mcp \
-H "Mcp-Session-Id: $SESSION_ID" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
--data '{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/list",
"params": {}
}' 2>&1 | grep -A 5 "list_tables"Step 3: Describe a Table
# Let's examine the "customers" table
curl -X POST http://127.0.0.1:8000/mcp \
-H "Mcp-Session-Id: $SESSION_ID" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
--data '{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "describe_table",
"arguments": {"table_name": "customers"}
}
}' 2>&1 | tail -20Step 4: Query Data
# Count customers
curl -X POST http://127.0.0.1:8000/mcp \
-H "Mcp-Session-Id: $SESSION_ID" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
--data '{
"jsonrpc": "2.0",
"id": 4,
"method": "tools/call",
"params": {
"name": "sql_query",
"arguments": {
"statement": "SELECT COUNT(*) as total FROM customers"
}
}
}' 2>&1 | tail -20Step 5: Configure in Claude/Copilot
For Claude Desktop:
{
"mcpServers": {
"faircom": {
"type": "http",
"url": "http://127.0.0.1:8000/mcp"
}
}
}For GitHub Copilot (VS Code):
{
"mcpServers": {
"faircom": {
"type": "http",
"url": "http://127.0.0.1:8000/mcp"
}
}
}Then ask your AI assistant: "Show me a count of customers by region" – it will use FairCom MCP to execute the query.
Configuration
Edit /etc/faircom-mcp/faircom-mcp.env (package install) or pass as environment variables (Docker):
# Required: FairCom connectivity
FAIRCOM_API_BASE_URL=https://faircom.example.com:9443
FAIRCOM_API_USERNAME=ADMIN # or use FAIRCOM_API_TOKEN
FAIRCOM_API_PASSWORD=ADMIN
# Optional: Server binding
FAIRCOM_HTTP_HOST=0.0.0.0
FAIRCOM_HTTP_PORT=8000
# Optional: TLS
## Connector Management
FairCom MCP exposes connector inspection and lifecycle operations for FairCom Edge input and output connectors.
Read-oriented connector tools:
- `list_inputs(payload?)`
- `describe_inputs(payload)` — `payload.inputNames` (non-empty list of strings) is required; call `list_inputs` first to discover names.
- `list_outputs(payload?)`
- `describe_outputs(payload?)`
CamelCase parity aliases are also available for API-name alignment:
- `listInputs(payload?)`
- `describeInputs(payload?)`
- `listOutputs(payload?)`
- `describeOutputs(payload?)`
Write-oriented connector tools:
- `create_input(payload, confirm_write=False, dry_run=False)`
- `alter_input(payload, confirm_write=False, dry_run=False)`
- `delete_input(payload, confirm_write=False, dry_run=False)`
- `create_output(payload, confirm_write=False, dry_run=False)`
- `alter_output(payload, confirm_write=False, dry_run=False)`
- `delete_output(payload, confirm_write=False, dry_run=False)`
CamelCase parity aliases are also available for write operations:
- `createInput(payload, confirm_write=False, dry_run=False)`
- `alterInput(payload, confirm_write=False, dry_run=False)`
- `deleteInput(payload, confirm_write=False, dry_run=False)`
- `createOutput(payload, confirm_write=False, dry_run=False)`
- `alterOutput(payload, confirm_write=False, dry_run=False)`
- `deleteOutput(payload, confirm_write=False, dry_run=False)`
Connector writes follow the same explicit safety model as SQL writes:
1. Use `dry_run=True` first to preview the intended connector change.
2. Review the returned action and target payload.
3. Re-run with `confirm_write=True` to apply the change.
Example preview:
```json
{
"name": "create_output",
"arguments": {
"payload": {
"outputName": "writeTemperatureToModbus",
"serviceName": "modbus",
"tableName": "modbusTableTCP",
"sourceFields": ["source_payload"],
"modbusProtocol": "TCP",
"modbusServer": "127.0.0.1",
"modbusServerPort": 502
},
"dry_run": true
}
}Example apply:
{
"name": "create_output",
"arguments": {
"payload": {
"outputName": "writeTemperatureToModbus",
"serviceName": "modbus",
"tableName": "modbusTableTCP",
"sourceFields": ["source_payload"],
"modbusProtocol": "TCP",
"modbusServer": "127.0.0.1",
"modbusServerPort": 502
},
"confirm_write": true
}
}Flat modbus* properties are auto-nested under settings before the request reaches FairCom, matching the shape FairCom's wire format expects. outputName is the output identity field; connectorName is also accepted as an alias and renamed automatically.
mqtt is not a valid serviceName for create_input/create_output. MQTT delivery is configured through MQ topic bindings instead — see MQTT Delivery (MQ Topics) below.
The server does not auto-discover device register maps or connector-specific address models. Supply the connector payload details required by the FairCom Edge configuration API for the connector family you are managing.
MQTT Delivery (MQ Topics)
MQTT delivery in FairCom Edge does not go through create_output. There is no mqtt integration service to enable and no mqtt output connector. Instead, an MQTT topic is bound directly to an integration table through the JSON MQ API's topic actions; records inserted into that table are then published to subscribers of the topic.
Read-oriented tools:
list_topics(payload?)— list MQTT topic names the server is tracking.describe_topics(payload?)— describe topics, including their bound table and transform settings.
Write-oriented tools:
configure_topic(payload, confirm_write=False, dry_run=False)— create or update (upsert) a topic binding. Unlikecreate_input/create_output, this is an upsert, not a create-only action.delete_topic(payload, confirm_write=False, dry_run=False)
Example:
{
"name": "configure_topic",
"arguments": {
"payload": {
"topic": "factory/line-1/mixing_tank/temperature",
"databaseName": "faircom",
"tableName": "modbus_mixing_tank_temp"
},
"confirm_write": true
}
}configureTopic also accepts transformName to transform messages before they are stored, plus downgradeQoS and maxDeliveryRatePerSecond (defaults come from defaultDowngradeQoS/defaultMaxDeliveryRatePerSecond in FairCom's services.json). After configuring, configure_topic's response includes mutation_applied/mutation_verification, since the write is verified with a describe_topics read-back rather than trusted blindly.
FairCom JSON API Surface
FairCom's JSON API is split into three separate namespaces, selected by the api field on every request:
db— SQL query/execute and table metadata (sql_query,sql_query_page,sql_execute, table tools).hub— Edge connector lifecycle (createInput/createOutputand friends), plus integration tables and theirtransformSteps.admin— code packages, accounts, and other server administration actions.
There is no single unified endpoint that covers all three — for example, a JavaScript transform is not one object. It is a code package registered through admin and then attached to an integration table's transformSteps through hub. FairCom MCP routes each tool call to the correct namespace and payload shape automatically so you don't need to track this split yourself, but if you see an upstream error referencing an api value, this is why.
FAIRCOM_TLS_VERIFY=true # Set to false for self-signed certs
Optional: Safety controls
FAIRCOM_POLICY_PRESET=default # default, read_only, analyst, operator, admin FAIRCOM_TOOL_GROUP_ALLOWLIST=metadata,query,write,admin,diagnostics FAIRCOM_SQL_ALLOWLIST=SELECT,INSERT,UPDATE,DELETE FAIRCOM_SQL_DENYLIST=DROP,TRUNCATE,ALTER
## Available Tools
| Tool | Purpose | Safety |
|---|---|---|
| `list_tables(name_like?)` | Discover tables | Read-only |
| `describe_table(table_name)` | Get columns, indexes, constraints (falls back to integration table metadata) | Read-only |
| `list_table_columns(table_name)` | Column names and types (works for integration tables too) | Read-only |
| `list_table_indexes(table_name)` | Index details | Read-only |
| `sql_query(statement, params?)` | Execute SELECT (read-only) | Read-only |
| `sql_query_page(statement, params?, page, page_size)` | Paginated SELECT | Read-only |
| `sql_execute(statement, params?, confirm_write, dry_run)` | INSERT/UPDATE/DELETE (requires `confirm_write=true` unless `dry_run=true`) | Write |
| `list_services(payload?)` | List Edge connector services and runtime state | Read-only |
| `manage_service(payload, confirm_write, dry_run)` | Start/stop/restart a connector service | Write |
| `describe_connector_schema(payload?)` | Local payload schema profiles and known-good examples per connector service and direction (input/output) | Read-only |
| `validate_connector_payloads(payload)` | Preflight-validate connector payloads without mutating backend state, including cross-checking `serviceName` against `list_services` | Read-only |
| `get_usage_contract()` | Canonical args, aliases, transport/session guidance, examples | Read-only |
| `runtime_status()` | Health, version, diagnostics | Read-only |
| `capabilities_summary()` | Discover enabled tool groups and policy preset | Read-only |
| `observability_metrics()` | Snapshot of internal runtime metrics | Read-only |
| `observability_audit()` | Snapshot of the write/audit event log | Read-only |
| `observability_health()` | Readiness/liveness state as an MCP tool call | Read-only |
| `list_topics(payload?)` | List MQTT topic names being tracked | Read-only |
| `describe_topics(payload?)` | Describe MQTT topics, including bound table and transform settings | Read-only |
| `configure_topic(payload, confirm_write, dry_run)` | Upsert an MQTT topic binding to an integration table | Write |
| `delete_topic(payload, confirm_write, dry_run)` | Delete an MQTT topic binding | Write |
See [Connector Management](#connector-management) for input/output connector tools, [Integration Tables & Code Packages](#integration-tables--code-packages) for transform pipeline tools, and [MQTT Delivery (MQ Topics)](#mqtt-delivery-mq-topics) for MQTT publish tools.
## Integration Tables & Code Packages
Integration tables capture data landed by an input connector and apply `transformSteps` to it. A transform step's JavaScript logic lives in a separately registered code package; a table then references it by `codeName`. There is no single "transform" object — FairCom splits this across the `hub` API (integration tables) and the `admin` API (code packages), and FairCom MCP routes each tool call to the correct one for you.
Read-oriented tools:
- `list_integration_tables(payload?)` — list integration tables visible to the configured access context.
- `describe_integration_tables(payload)` — describe tables including their `fields` and `transformSteps`. Pass a `tables` array, not a bare `tableName`.
- `list_code_packages(payload?)` — list registered code package names for a database/owner.
- `describe_code_packages(payload)` — describe registered code packages, including source code.
Write-oriented tools (same `dry_run` / `confirm_write` safety model as SQL and connector writes):
- `create_integration_table(payload, confirm_write, dry_run)` — create a table, optionally with `fields` and `transformSteps` in the same call.
- `alter_integration_table(payload, confirm_write, dry_run)` — alter a table's fields, transform steps, or retention policy. The server polls `describe_integration_tables` after the write and reports `mutation_applied` / `mutation_verification` in the response, because FairCom can return success while silently not applying some field or transform-step changes.
- `delete_integration_tables(payload, confirm_write, dry_run)`
- `register_code_package(payload, confirm_write, dry_run)` — create or update a code package (`createCodePackage`/`alterCodePackage`). Accepts `input_fields` (list of field names the transform reads) and `output_field_definitions` (list of `{name, type}` objects the transform writes); both are merged into `metadata.inputFields`/`metadata.outputFieldDefinitions`.
- `clone_code_package(payload, confirm_write, dry_run)` — clone an existing code package under a new name.
- `revert_code_package(payload, confirm_write, dry_run)` — revert a code package to a prior version. There is no delete; re-registering the same `code_name` is how you update it.
- `test_integration_table_transform_steps(payload, confirm_write, dry_run)` — dry-run transform steps against a table. `payload.testTransformScope` is required and validated against the known enum (`allRecords`, `stop`, `firstRecord`, `lastRecord`, `specificRecords`) since FairCom's own error does not list valid values.
Important, field-tested gotchas:
- Declare every target field in `create_integration_table`'s `fields` array up front. Neither the transform nor `alter_integration_table` can reliably add fields to an existing table afterward.
- Put `databaseName` and `ownerName` inside each transform step object, not only at the table's top level, or FairCom rejects the step with a missing-default-database error.
- A `transformStepMethod` of `"javascript"` requires `transformStepService: "v8TransformService"` alongside it.
- Set `input_fields`/`output_field_definitions` on `register_code_package` for `integrationTableTransform` packages. Without `metadata.inputFields`/`metadata.outputFieldDefinitions`, the code package is created successfully but the FairCom Edge Explorer wizard reports "no suitable Integration Table Transform Code Packages" and cannot find it — the Code Editor GUI sets these automatically, but the Code Package API does not. `register_code_package` returns a `warnings` entry naming the missing property when this happens. **Unverified:** the exact shape this tool writes (`metadata.inputFields`/`metadata.outputFieldDefinitions`) has not been confirmed to resolve wizard visibility in all environments — `register_code_package` always includes an `UNVERIFIED` warning when these fields are set as a reminder to check the wizard after registering. If the wizard still can't find the package, compare against the metadata a Code Editor-created package actually has.
## Common AI Client Mistakes (And Fixes)
These are the most common payload issues across Claude, Copilot, ChatGPT, Gemini, and custom agents.
### 1) Wrong key for `sql_query`
Wrong:
```json
{"name":"sql_query","arguments":{"sql":"SELECT COUNT(*) FROM demo_assets"}}Correct canonical form:
{"name":"sql_query","arguments":{"statement":"SELECT COUNT(*) FROM demo_assets"}}Notes:
The server accepts aliases
sqlandquery, normalizes tostatement, and returns normalization metadata.The server also normalizes
SELECT FIRST N ...toSELECT TOP N ...for FairCom compatibility.
2) Wrong key for table metadata tools
Wrong:
{"name":"describe_table","arguments":{"table":"demo_assets"}}Correct canonical form:
{"name":"describe_table","arguments":{"table_name":"demo_assets"}}Notes:
The server accepts
tablealias and normalizes totable_name.
3) list_tables filtering key mismatch
Wrong:
{"name":"list_tables","arguments":{"table_like":"demo_%"}}Correct canonical form:
{"name":"list_tables","arguments":{"name_like":"demo_%"}}Notes:
table_likeis accepted as an alias and normalized toname_like.databaseis accepted for compatibility; current adapter may ignore backend scoping and reports that explicitly.
4) SQL dialect mismatch (LIMIT/OFFSET/FETCH)
Risky for this backend:
SELECT * FROM demo_assets ORDER BY id DESC LIMIT 25 OFFSET 10Preferred FairCom-compatible style:
SELECT SKIP 10 TOP 25 * FROM demo_assets ORDER BY id DESCNotes:
The server returns a structured validation error with
suggested_fixandexample_payloadfor unsupported SQL feature patterns.Unsupported SQL tokens are reported explicitly in
unsupported_sql_feature(for example:LIMIT,OFFSET,FETCH).
Session Recovery Quick Fix
If you receive a missing/stale session error:
Call
initializeagain.Capture the new
Mcp-Session-Id.Retry the failed
tools/callrequest with the new session id.
Tip:
Call
get_usage_contractonce at startup to load canonical argument keys and aliases.A versioned contract snapshot is also published at
docs/mcp-usage-contract.v2026-07-28.json.
JSON Mode vs SSE Mode
--transport http: best for JSON-only clients.--transport sse: best for clients that parsetext/event-streamframing.--transport stdio: local process transport for MCP hosts.
If your parser is brittle against SSE envelopes, run the server in HTTP mode and keep request/response handling strictly JSON.
Project-Provided JSON-RPC Helper Clients
Reference helper clients are available for strict JSON-RPC integrations:
examples/clients/python/mcp_http_helper.pyexamples/clients/javascript/mcpHttpHelper.mjs
These helpers implement the compatibility workflow used by this server:
initialize session before tool calls
reuse
Mcp-Session-Idforce
Accept: application/jsonfor deterministic JSON modereinitialize once and retry when
reason_codeindicatesmissing_sessionorstale_sessionpreview writes using
sql_executewithdry_run=true
Observability & Operations
Health Endpoints
GET /health # Simple health check (JSON)
GET /healthz # Kubernetes-style liveness
GET /ready # Readiness check (JSON)
GET /readyz # Kubernetes-style readiness
GET /metrics # Prometheus-compatible metrics
GET /diagnostics # Human-readable diagnostics
GET /diagnostics/json # Machine-readable diagnosticsLogs
Package install:
journalctl -u faircom-mcp -f # Follow logs
journalctl -u faircom-mcp --since 1h # Last hourDocker:
docker logs -f faircom-mcpLog Rotation
Package install includes logrotate policy:
/var/log/faircom-mcp/faircom-mcp.log {
daily
rotate 7
compress
delaycompress
notifempty
missingok
}Development
See BUILD.md for building, testing, and releasing.
Community
Issues: GitHub Issues
Discussions: GitHub Discussions
Contributing: See CONTRIBUTING.md (coming soon)
License
Licensed under the Apache License, Version 2.0. See LICENSE for terms.
Support
This independent proof of concept is not supported by FairCom. For issues with this project or its MCP integration, open a GitHub issue.
For questions about FairCom products themselves, see https://www.faircom.com/support.
An independent proof of concept built for experimentation with FairCom products and adaptable to other backends.
Available Tools
42 toolsalter_inputC
Modify settings on an existing input connector.
Inputs: dry_run, payload, confirm_write. Returns: result
alter_integration_tableB
Alter an integration table's fields, transform steps, or retention policy.
Inputs: dry_run, payload, confirm_write. Returns: result
alter_outputC
Modify settings on an existing output connector.
Inputs: dry_run, payload, confirm_write. Returns: result
capabilities_summaryA
Summarize the tools this MCP server exposes and their write-safety model.
Inputs: no named parameters. Returns: result
clone_code_packageB
Clone an existing code package under a new name.
Inputs: code_name (required), new_code_name (required), dry_run, owner_name, +2 more. Returns: result
configure_topicC
Create or update an MQTT topic and bind it to an integration table.
Inputs: dry_run, payload, confirm_write. Returns: result
create_inputC
Create a new input connector that collects data from a device or software system.
Inputs: dry_run, payload, confirm_write. Returns: result
create_integration_tableB
Create an integration table, optionally with fields and transform steps.
Inputs: dry_run, payload, confirm_write. Returns: result
create_outputB
Create a new output connector that delivers collected data to an external service.
Inputs: dry_run, payload, confirm_write. Returns: result
delete_inputC
Delete an input connector definition.
Inputs: dry_run, payload, confirm_write. Returns: result
delete_integration_tablesC
Delete one or more integration tables.
Inputs: dry_run, payload, confirm_write. Returns: result
delete_outputC
Delete an output connector definition.
Inputs: dry_run, payload, confirm_write. Returns: result
delete_topicC
Delete an MQTT topic.
Inputs: dry_run, payload, confirm_write. Returns: result
describe_code_packagesC
Describe one or more code packages by name.
Inputs: code_names (required), owner_name, code_format, database_name. Returns: result
describe_connector_schemaC
Describe the expected input or output connector payload schema for a service.
Inputs: service_name (required), direction. Returns: result
describe_inputsA
Describe one or more input connectors by name (payload.inputNames is required; call list_inputs first to discover names).
Inputs: payload. Returns: result
describe_integration_tablesC
Describe one or more integration tables, including fields and transform steps.
Inputs: payload. Returns: result
describe_outputsB
Describe one or more output connectors by name.
Inputs: payload. Returns: result
describe_tableB
Describe a table's columns and metadata by name.
Inputs: table, table_name. Returns: result
describe_topicsB
Describe one or more MQTT topics by name.
Inputs: payload. Returns: result
get_usage_contractA
Return this server's tool usage contract: argument aliases, canonical arg names, and payload examples.
Inputs: no named parameters. Returns: result
list_code_packagesC
List registered code packages.
Inputs: name_like, owner_name, max_records, database_name, +2 more. Returns: result
list_inputsA
List the names of previously created input connectors.
Inputs: payload. Returns: result
list_integration_tablesC
List integration tables in a database.
Inputs: payload. Returns: result
list_outputsC
List the names of previously created output connectors.
Inputs: payload. Returns: result
list_servicesA
List FairCom services and their runtime state (enabled/running/disabled).
Inputs: payload. Returns: result
list_table_columnsC
List the columns defined on a table, including integration tables.
Inputs: table, table_name. Returns: result
list_table_indexesC
List the indexes defined on a table.
Inputs: table, table_name. Returns: result
list_tablesC
List database tables, optionally filtered by a name pattern.
Inputs: database, name_like, table_like. Returns: result
list_topicsA
List the names of MQTT topics the server is tracking.
Inputs: payload. Returns: result
manage_serviceB
Pause, resume, restart, shut down, or start up a FairCom service.
Inputs: dry_run, payload, confirm_write. Returns: result
observability_auditA
Return recent audit log entries for write operations performed through this server.
Inputs: no named parameters. Returns: result
observability_healthB
Return this MCP server's health status.
Inputs: no named parameters. Returns: result
observability_metricsB
Return this MCP server's own operational metrics.
Inputs: no named parameters. Returns: result
register_code_packageC
Create or update a JavaScript code package, such as an integration table transform.
Inputs: code (required), code_name (required), comment, dry_run, +9 more. Returns: result
revert_code_packageC
Revert a code package to a prior version.
Inputs: version (required), code_name (required), dry_run, owner_name, +2 more. Returns: result
runtime_statusA
Report this MCP server's own runtime and configuration status.
Inputs: no named parameters. Returns: result
sql_executeB
Execute a write SQL statement (insert/update/delete) against FairCom.
Inputs: sql, query, params, dry_run, +2 more. Returns: result
sql_queryB
Run a read-only SQL query against a FairCom database.
Inputs: sql, query, params, statement. Returns: result
sql_query_pageB
Run a read-only SQL query and return one page of results at a time.
Inputs: sql, page, query, params, +4 more. Returns: result
test_integration_table_transform_stepsB
Test an integration table's transform steps against records before applying them for real.
Inputs: dry_run, payload, confirm_write. Returns: result
validate_connector_payloadsA
Validate one or more connector payloads locally without writing to FairCom.
Inputs: action, payload, payloads. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 42 tools
Most tools have clear resource+action pairs, but list_table_columns and describe_table overlap in column information, and sql_query vs sql_query_page could cause confusion. The list/describe pattern for inputs/outputs/integration tables is otherwise distinct.
The list/describe/create/alter/delete prefix pattern is consistent, but observability_*, capabilities_summary, runtime_status, and sql_query/sql_execute use noun phrases or different verb styles. This mixing of conventions is noticeable but still readable.
42 tools is excessive. Even for a broad integration server, many could be consolidated (e.g., observability_* group, list vs describe pairs). The count exceeds the typical heavy threshold and may overwhelm agents.
The tool set provides full CRUD-like coverage for connectors, integration tables, MQTT topics, and code packages, plus SQL read/write, validation, testing, and observability. There are no obvious dead ends for core workflows.
Maintenance
Related MCP Connectors
Governed data discovery, exact queries, decisions, simulations, and runtime utilities over MCP.
Cloud-hosted MCP server for secure AI access to enterprise data sources via CData Connect AI.
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
ZEN SecDB MCP server for CVE intelligence, CVSS/EPSS scoring, advisories, SSVC, and package audits.
Related MCP Servers
- AlicenseBqualityBmaintenanceEnables MCP hosts to use NeoSQL Desktop tools for database management, including querying, table operations, and code generation, through a local stdio MCP server.10476 npm2Apache 2.0
- FlicenseNot gradedqualityDmaintenanceEnables interaction with U2 UniData/UniVerse databases through MCP tools for file, record, dictionary, and BP program operations, with built-in admin UI, JWT authentication, RBAC, and audit logging.-
- AlicenseNot gradedqualityDmaintenanceEnables SQL query execution and database structure browsing via MCP tools and resources.MIT
- FlicenseNot gradedqualityDmaintenanceA versatile MCP server that connects to multiple relational databases (MySQL, PostgreSQL, Oracle, SQL Server, SQLite) and enables secure read-only SQL query execution and metadata access.4-