HQbird MCP AI assistant
AI assistant under human control
HQbird MCP connects Firebird to an AI assistant. You write in plain words, and the assistant picks the tools itself. It reads freely. Each change waits for your “yes”, and a dangerous one waits for approval on the server itself.
- 122 tools
- 56 read only
- Firebird 2.5–5 Windows and Linux
- 2 channels for approval
- audit log with a hash chain
Example
A conversation with the assistant
Users complain that the database is slow. The assistant reads the data, finds the cause, suggests an action and waits for your decision. Names and numbers in the example are made up.
Any MCP client works: Claude Desktop, Claude Code, Cursor, Codex, ZCode and others.
Policy · approval
Four danger levels
Each tool has a level. The MCP server checks the level and the conditions itself before the call runs. A call that changes something returns an approval request, not a result. The assistant cannot bypass this check.
Pick a tool and see which path its call takes.
| Level | Tools | Examples | How it is approved |
|---|---|---|---|
| 0 · Read | 51 | sessions, transactions, query plan, gstat, firebird.log, agent reports | Not needed. Read-only transaction. |
| 1 · Change | 31 | DML and DDL, backup, test restore, sweep, users and grants, ending a session | In chat: request number and token, then fb_confirm. |
| 2 · Dangerous operation | 14 | replace a database from a backup, edit firebird.conf, stop and restart Firebird | On the server only: the fbmcp ctl approve command. On Windows you can also install a tray window. |
| 3 · Disabled | 1 | drop a database | Never runs. |
- PreviewEach tool that needs approval accepts
mode: preview. It shows what will be done and does nothing. - Conditions for level 2Each level 2 operation needs an open maintenance window on that database. Replacing a database from a backup, an exclusive window and dangerous SQL also need a verified backup no older than 24 hours. A refusal says what is missing.
- Only allowed toolsThe client sees in the list only what it is allowed to use: no level 3 and no levels above the maximum of its key. A direct call to a hidden tool is refused.
- A request lives 15 minutesAn attempt to approve it through the wrong channel does not use it up.
fb_canceldeletes the request. - No approval pageAnd there will be none: a page that the model can reach would break the protection. Only a person on the server approves: with the
fbmcp ctl approvecommand or in the tray window, if it is installed.
Reads run in a read-only transaction: Firebird itself blocks writes. For a second layer of protection, set a separate read-only user with no write rights.
Monitoring · backups · grants
For DBAs
The assistant does what a DBA does by hand: checks sessions and transactions, reads logs, makes a backup and verifies it with a restore, manages users. It names databases by id, not by file path.
| Task | Tools | Level |
|---|---|---|
| Is everything working | fb_ping, fb_db_list, fb_db_health, fb_service_status | 0 |
| Sessions and long transactions | fb_sessions, fb_transactions; to end a session — fb_session_kill | 0 · 1 |
| Logs and statistics | fb_firebird_log, fb_gstat, fb_lwmonitoring, fb_trends | 0 |
| Backup and verification | fb_backup_start (gbak), fb_backup_nbackup, fb_restore_test | 1 |
| Old backups | fb_retention_run: dry run first; deletes only verified backups from its own catalog | 1 |
| Sweep and database validation | fb_sweep, fb_validate (findings only, no repair) | 1 |
| Users and grants | fb_user_create, fb_grant, fb_revoke; SYSDBA and its own accounts cannot be deleted | 1 |
| Traces | fb_trace_start with templates only: audit-lite, performance, errors | 1 |
| firebird.conf | fb_config_get, fb_config_diff; to edit — fb_config_set, Firebird is not restarted | 0 · 2 |
| Service and database replacement | fb_service_restart; fb_restore_replace, the old file stays as .pre-restore | 2 |
Nightly backup check
The schedule is approved once, when it is created. After that it runs without a person. Each night you get a verified backup. You need one, for example, to replace a database from a backup.
- 1Schedule
fb_schedule_create, goalnightly_verify; approved once - 2Backupgbak to the backup folder
- 3Test restoreinto a work folder; the source database is not touched
- 4✓ Backup verifieda mark in the backup catalog
Database replacement from a backup and level 3 operations cannot be scheduled.
Ready-made scenarios
Scenarios suggest the order of steps to the assistant. It does not apply changes by itself.
Queries · indexes · migrations
For developers
The assistant in Cursor or Claude Code knows your schema, checks a query before it runs and shows the result as a table right in the chat.
- 1Taskwhat you need, in one sentence
- 2Facts
fb_schema_list,fb_describe: only existing tables and columns - 3Draftone SELECT with ORDER BY
- 4Check
fb_query_check: compile without running - 5✓ Table in chat
fb_query: rows, plan and statistics
Result as a table
In clients that support MCP Apps, the fb_query result is shown as a sortable table. Other clients get the same data as text.
100 rows by default, 1000 at most. The table stays in memory for 30 minutes, and only the person who asked for it can see it. Click a column header to sort.
SELECT full_name, dept_no, salary FROM employee WHERE salary > 60000 ORDER BY salary DESC
Index advice
Finds full table scans and suggests CREATE INDEX with an estimate of the benefit. It does not create the index itself: fb_write does that, with approval. After the index is created, it checks the plan again.
Database comparison
Schema of two databases, or of a database and its snapshot: what to create, change, drop. Data is compared by primary key; the tool does not compare a large table (by default, more than 100,000 rows).
Migrations
The plan shows the level of each statement. All migrations are applied after one approval; if a file changes, a new request is needed. The rollback plan is built from what was recorded when the migrations were applied.
fb_write finds the level of each statement in a script. A script that mixes statements of different levels is rejected.
fbagent · Local API · 127.0.0.1
fbagent data
The fbagent agent already runs on the HQbird server. Through MCP the assistant gets everything the agent collected: the health report, LWM (Light-weight Monitoring), gstat, traces, deadlocks, backup status. It also runs agent jobs and changes their settings, under the same levels and approvals.
| What | Tools | Level |
|---|---|---|
| Server health report | fb_agent_status | 0 |
| LWM, gstat, database metrics, traces, deadlocks | fb_agent_artifact_get, fb_agent_perf_report | 0 |
| Backup, sweep and restore settings | fb_agent_backup_config; passwords and tokens are hidden | 0 |
| Run an agent job | fb_agent_job_run; backup, restore and SQL script are level 2 | 1 · 2 |
| Change a job setting | fb_agent_config_set; credentials, ids and commands cannot be changed | 2 |
| Restart Firebird through the agent | fb_agent_restart, fb_agent_stop, fb_agent_start | 2 |
| License and updates | fb_agent_license, fb_agent_license_set, fb_agent_update_apply, fb_agent_product_update_apply | 0 · 1 · 2 |
- Local onlyThe agent accepts requests only on 127.0.0.1. The agent address comes from the MCP server configuration, not from the chat.
- Token stays hiddenThe agent token does not appear in tool output or in the audit log.
- Agent discovery
fb_agent_discoverfinds agents on the server by Windows services or systemd units. It does not read tokens. - ClusterIf a cluster node is installed on the server,
fb_agent_restart,fb_agent_stopandfb_agent_startrefuse by default: the node controls restarts.fb_service_restartdoes not check this, so do not use it on a cluster node.
Double control. The MCP server approves the request, and the agent itself runs the job, by its own rules. The MCP log shows who asked; the agent logs show how it was done.
HQbird Cluster · RCM
Replication cluster through the assistant
The assistant builds a replication cluster step by step: it turns on RCM, opens the pairing window, links the hosts, takes databases under management and makes a copy for the replica. It works through the agent and RCM. You do not need to log in to the servers over SSH.
The rules are the same as everywhere. Reads need no confirmation. A change is confirmed in the chat. A Firebird restart, a database copy to the replica, removing a server from the cluster, switchover, failover and the return of the old master are confirmed on the server.
| What | Tools | Level |
|---|---|---|
| Cluster state on the server | fb_agent_cluster: free, in a cluster or RCM owner; slot and ports | 0 |
| Cluster overview in RCM | fb_cluster_status: nodes, databases, commands, alerts | 0 |
| Check hosts before linking | fb_cluster_probe: a row per agent, certificate fingerprint | 0 |
| Compare master and replica | fb_cluster_verify: row count of each table | 0 |
| Turn on RCM on the server | fb_agent_cluster_rcm | 1 |
| Pairing window | fb_agent_cluster_pairing: state, open for 1–24 hours, close | 0 · 1 |
| Link hosts | fb_cluster_link; the request shows fingerprints to compare | 1 |
| Databases and publication | fb_cluster_replica_folder, fb_cluster_enroll, fb_cluster_publication | 1 |
| RCM password | fb_cluster_rcm_password: a new random password, not shown in the chat | 1 |
| Database copy to the replica | fb_cluster_reinit | 2 |
| Restart the Firebird of a node | fb_cluster_firebird_restart | 2 |
| Remove a server from the cluster | fb_cluster_unlink | 2 |
| Services: where the master is | fb_cluster_service: master, replicas, routers, problems, running operation | 0 |
| Describe a service and its rule | fb_cluster_service_put, fb_cluster_service_policy: service description, automatic failover rule | 1 |
| Resume and cancel an operation | fb_cluster_resume, fb_cluster_operation_cancel; cancel only before the point of no return | 1 |
| Switchover | fb_cluster_switchover: planned move of the master, waits for the end of the operation | 2 |
| Failover | fb_cluster_failover: only with explicit consent to data loss | 2 |
| Bring back the old master | fb_cluster_rejoin | 2 |
| Delete a service | fb_cluster_service_delete: only the record in RCM is deleted | 2 |
- Ready-made scenario“Build a cluster”: the assistant goes step by step and at each step shows what it will do.
- FingerprintsBefore linking, the assistant shows the certificate fingerprint of each server. Compare it with the line from the installation summary.
- Dry runBefore it takes a folder with databases under management, the assistant shows which databases RCM will find.
- Switchover and failoverThe assistant starts the move of the master and follows the steps of the operation. A person on the server confirms the start. Failover also needs explicit consent to data loss. More on the cluster page.
HTTPS · API keys · audit
Remote mode, installation and audit log
The assistant runs on the administrator’s PC, and the MCP server runs on the database server. Between them are HTTPS and an API key. Each person has their own key and their own maximum level.
- A key for each person
fbmcp ctl apikey new <name> --max-tier 2. The value is shown once. After a key change, the old key stops working within a few seconds. - LimitsPer key: concurrent calls, calls per minute, open sessions. Above the limit, the response is 429.
- Guide in PortugueseThe full guide to installation and use is also available in Brazilian Portuguese.
- Autonomous agentsThe
autonomousprofile: read only by default. A change waits for an operator on the server;fb_confirmfrom the agent is rejected. 10 calls per minute. Run such agents inside the company network. - AddressesA key can be bound to addresses (
allow_from). Another address gets 403 and an entry in the log.
Installation in HQbird
The HQbird installer installs the MCP server by default. One server serves all Firebird lines on the machine. One command sets up everything, and you can run it again.
- 1HQbird installerWindows or Linux
- 2fbmcp ctl hqbird-installone command, no manual YAML edits
- 3Firebird linesfinds each line and its agent
- 4Databasesdatabases.conf aliases and recently attached databases
- 5✓ Servicestart, check, connect.txt file for clients
Remote mode turns on when three conditions are met: a list of administrator addresses is set (--allow-from), the firewall is running, and at least one API key exists. You create the key separately. After that, run fbmcp ctl hqbird-install again. The default port is 8650.
Hash chain
Each decision (allowed, pending, approved, rejected) is written to the log. Each entry is linked to the previous one. A chain check shows if an entry was changed or deleted.
Log cut short — server stays down
If the log is cut short or its end does not match the control entry, the MCP server does not start. This is a sign of tampering, and you must investigate it. The fbmcp ctl verify command checks the whole chain.
Through the agent
fbagent updates the MCP server: stop, replace, start, check, roll back on failure. On Linux an unsigned build is not installed. Configuration and keys do not change.