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.

    Call path: assistant, fbmcp policy check, four levels, audit log
    LevelToolsExamplesHow it is approved
    0 · Read51sessions, transactions, query plan, gstat, firebird.log, agent reportsNot needed. Read-only transaction.
    1 · Change31DML and DDL, backup, test restore, sweep, users and grants, ending a sessionIn chat: request number and token, then fb_confirm.
    2 · Dangerous operation14replace a database from a backup, edit firebird.conf, stop and restart FirebirdOn the server only: the fbmcp ctl approve command. On Windows you can also install a tray window.
    3 · Disabled1drop a databaseNever 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_cancel deletes 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 approve command 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.

    TaskToolsLevel
    Is everything workingfb_ping, fb_db_list, fb_db_health, fb_service_status0
    Sessions and long transactionsfb_sessions, fb_transactions; to end a session — fb_session_kill0 · 1
    Logs and statisticsfb_firebird_log, fb_gstat, fb_lwmonitoring, fb_trends0
    Backup and verificationfb_backup_start (gbak), fb_backup_nbackup, fb_restore_test1
    Old backupsfb_retention_run: dry run first; deletes only verified backups from its own catalog1
    Sweep and database validationfb_sweep, fb_validate (findings only, no repair)1
    Users and grantsfb_user_create, fb_grant, fb_revoke; SYSDBA and its own accounts cannot be deleted1
    Tracesfb_trace_start with templates only: audit-lite, performance, errors1
    firebird.conffb_config_get, fb_config_diff; to edit — fb_config_set, Firebird is not restarted0 · 2
    Service and database replacementfb_service_restart; fb_restore_replace, the old file stays as .pre-restore2

    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.

    1. 1Schedulefb_schedule_create, goal nightly_verify; approved once
    2. 2Backupgbak to the backup folder
    3. 3Test restoreinto a work folder; the source database is not touched
    4. 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.

    Health check Optimization Security audit DDL review Migration plan Disaster readiness Query builder

    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.

    1. 1Taskwhat you need, in one sentence
    2. 2Factsfb_schema_list, fb_describe: only existing tables and columns
    3. 3Draftone SELECT with ORDER BY
    4. 4Checkfb_query_check: compile without running
    5. 5✓ Table in chatfb_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
    6 rows · PLAN SORT (EMPLOYEE NATURAL) · read only
    fb_index_advice

    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.

    fb_diff_schema · fb_diff_data

    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).

    fb_migration_*

    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.

    WhatToolsLevel
    Server health reportfb_agent_status0
    LWM, gstat, database metrics, traces, deadlocksfb_agent_artifact_get, fb_agent_perf_report0
    Backup, sweep and restore settingsfb_agent_backup_config; passwords and tokens are hidden0
    Run an agent jobfb_agent_job_run; backup, restore and SQL script are level 21 · 2
    Change a job settingfb_agent_config_set; credentials, ids and commands cannot be changed2
    Restart Firebird through the agentfb_agent_restart, fb_agent_stop, fb_agent_start2
    License and updatesfb_agent_license, fb_agent_license_set, fb_agent_update_apply, fb_agent_product_update_apply0 · 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 discoveryfb_agent_discover finds 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_stop and fb_agent_start refuse by default: the node controls restarts. fb_service_restart does 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.

    WhatToolsLevel
    Cluster state on the serverfb_agent_cluster: free, in a cluster or RCM owner; slot and ports0
    Cluster overview in RCMfb_cluster_status: nodes, databases, commands, alerts0
    Check hosts before linkingfb_cluster_probe: a row per agent, certificate fingerprint0
    Compare master and replicafb_cluster_verify: row count of each table0
    Turn on RCM on the serverfb_agent_cluster_rcm1
    Pairing windowfb_agent_cluster_pairing: state, open for 1–24 hours, close0 · 1
    Link hostsfb_cluster_link; the request shows fingerprints to compare1
    Databases and publicationfb_cluster_replica_folder, fb_cluster_enroll, fb_cluster_publication1
    RCM passwordfb_cluster_rcm_password: a new random password, not shown in the chat1
    Database copy to the replicafb_cluster_reinit2
    Restart the Firebird of a nodefb_cluster_firebird_restart2
    Remove a server from the clusterfb_cluster_unlink2
    Services: where the master isfb_cluster_service: master, replicas, routers, problems, running operation0
    Describe a service and its rulefb_cluster_service_put, fb_cluster_service_policy: service description, automatic failover rule1
    Resume and cancel an operationfb_cluster_resume, fb_cluster_operation_cancel; cancel only before the point of no return1
    Switchoverfb_cluster_switchover: planned move of the master, waits for the end of the operation2
    Failoverfb_cluster_failover: only with explicit consent to data loss2
    Bring back the old masterfb_cluster_rejoin2
    Delete a servicefb_cluster_service_delete: only the record in RCM is deleted2
    • 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.

    Admin PC with an MCP client and fbmcp bridge, HTTPS through a firewall to the fbmcp service; fbmcp talks to Firebird and fbagent; a person on the server approves dangerous requests
    Remote mode. The bridge on the PC takes the key from the OS key store and checks the server certificate by pin. Passwords and database paths do not reach the chat: databases are named by id.
    • A key for each personfbmcp 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 autonomous profile: read only by default. A change waits for an operator on the server; fb_confirm from 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.

    1. 1HQbird installerWindows or Linux
    2. 2fbmcp ctl hqbird-installone command, no manual YAML edits
    3. 3Firebird linesfinds each line and its agent
    4. 4Databasesdatabases.conf aliases and recently attached databases
    5. 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.

    audit.jsonl

    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.

    Failure — stop

    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.

    Update

    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.

    ← Back to the HQbird 2027 overview