harbor-mcp-server
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., "@harbor-mcp-server What is the monthly recurring revenue by plan?"
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.
harbor-mcp-server
An MCP server that gives an AI agent access to a subscription business's database — without giving it the database.
Reads are parsed and allowlisted before they run. Personal data is masked on the way out. Writes require a preview and a confirmation token. Everything is written to an audit log the agent cannot read.
npx harbor-mcp-serverThat is the whole setup — no native addon to compile, no database to provision. It ships with a seeded demo database of 140 customers, ~1,950 invoices, ~260 support tickets and 90 days of usage events, so there is nothing to configure before you can ask it a question.
Why this exists
"Let Claude query our database" is a two-line proof of concept and a genuinely hard production problem. The gap between them is not the SQL — it is everything you have to be sure of before you point a language model at a table containing real customers.
This server is the second thing, built small enough to read in one sitting.
Related MCP server: sql-explorer-mcp
What it refuses to do
Each of these is enforced by parsing the statement into an AST, not by pattern-matching the string. Regex checks for DROP are defeated by comments, casing and string literals; they are not used for the decision.
Attempt | Result |
| Rejected — only SELECT is permitted |
| Rejected — statement stacking |
| Rejected — stacking hidden behind a comment |
| Rejected — table not on the allowlist |
| Rejected — schema introspection is via tools, not SQL |
| Rejected — disallowed table in a subquery |
| Rejected — banned function |
| Allowed, clamped to 500 rows |
| Rejected — unbounded scan of a large table |
| Allowed — aggregates bound their own output |
Every rejection carries a hint naming the specific table, column or clause that caused it, so the agent can correct itself rather than retrying blind:
Only SELECT is permitted; received "DELETE".
How to fix: This server is read-only. To change data, use issue_refund or
extend_trial, which require explicit confirmation.What it masks
Email, phone and address columns come back partially redacted:
| company_name | email |
| --------------- | -------------------------------- |
| Camden Digital | ke***********@camdendigital.com |
| Beacon Robotics | to************@beaconrobotics.com|Masking happens on the way out, keyed on column name, which means it survives SELECT *, joins, and aliases. Filtering still works on the real value — searching priya finds her, the response just will not hand you her address book entry.
Set HARBOR_REVEAL_PII=true to turn it off.
How writes work
Writes are disabled unless the operator sets HARBOR_ALLOW_WRITES=true, and even then they cannot fire in one call.
Call 1 — no token. Nothing changes; you get a preview:
## Refund preview — nothing has changed yet
Invoice **inv_00002** for customer **cus_0001**
- Charged: $49.00
- Already refunded: $0.00
- **This refund: $10.00**
- After: $10.00 refunded of $49.00
- Reason: Service outage goodwill credit
To execute, call again with `confirm_token: "DJ7-O9d14gtk"`. Expires in 300s.Call 2 — same arguments plus that token. Now it happens.
The preview is the point. It renders as plain text in the transcript, so a human reading along sees the exact amount and the exact invoice before anything is written. And because tokens live in process memory, a model that hallucinates a refund cannot execute one — it cannot invent a token that exists.
Tokens are single-use, expire in five minutes, and are bound to the exact arguments they were issued for. Replaying one with a larger amount_cents fails. A rejected attempt burns the token rather than letting an agent grind against it.
The audit log
Every call is recorded before the caller gets a response — allowed, denied or errored:
allowed harbor_run_query rows= 1 16ms customers
denied harbor_run_query rows= 0 2ms Only SELECT is permitted; received "DELETE".
allowed harbor_issue_refund rows= 0 66ms preview
allowed harbor_issue_refund rows= 1 71ms executedThe table is deliberately outside the allowlist. The agent writes to it by acting and cannot read, mine or edit it — so after a session you can answer "what did it actually do?" without trusting the agent's own account.
Tools
Tool | Purpose |
| Readable tables, row counts, and a note on each |
| Columns, types, nullability, which are masked |
| Guarded SELECT — the general-purpose escape hatch |
| Turn "the Kestrel account" into a customer id |
| Profile, subscription, billing, tickets, usage in one call |
| Revenue by month, plan, country or industry |
| Refund an invoice — two-step |
| Extend a trial — two-step |
One flexible query tool plus a few composite ones, rather than thirty narrow endpoints. An agent that can write SQL will out-compose any fixed set of endpoints; the guard is what makes that safe. The composite tools exist because some questions get asked constantly and deserve a single round trip.
harbor_revenue_summary also encodes a trap worth knowing about: trialing and canceled subscriptions carry mrr_cents = 0, so a naive AVG(mrr_cents) across all rows understates ARPA. The tool uses the right denominator so the agent does not have to know that.
Install
Claude Desktop
claude_desktop_config.json:
{
"mcpServers": {
"harbor": {
"command": "npx",
"args": ["-y", "harbor-mcp-server"]
}
}
}To allow refunds and trial extensions:
{
"mcpServers": {
"harbor": {
"command": "npx",
"args": ["-y", "harbor-mcp-server"],
"env": { "HARBOR_ALLOW_WRITES": "true" }
}
}
}Claude Code
claude mcp add harbor -- npx -y harbor-mcp-serverFrom source
git clone https://github.com/aayushsinghm16/harbor-mcp-server
cd harbor-mcp-server
npm install
npm run build
npm test
node dist/index.jsConfiguration
Variable | Default | Effect |
|
| Database location. |
|
| Enables |
|
| Returns email, phone and address unmasked. |
Requires Node 22.5+. Hard limits live in src/constants.ts: 500 rows maximum, 50 by default, 25,000 characters per response, $500 maximum single refund, 30 days maximum trial extension.
Things to try
Point Claude at it and ask:
"Which customers churned, and what reasons did they give?"
"Show me revenue by month for the first half of 2026."
"Which plan carries the most MRR, and what's the average per account?"
"Tell me everything about the Kestrel account." — one
customer_360call"Which accounts have both an open ticket and a failed payment?" — the churn-risk query
"Delete all the invoices." — watch it get refused, with a reason
The last one is the interesting one.
What this does not do
Being straight about the edges, because a security README that claims everything is a security README you should not trust.
Queries cannot be interrupted mid-flight. node:sqlite is synchronous and exposes no binding for sqlite3_interrupt, so the time budget is enforced by refusing expensive plans up front and by capping rows — not by killing a running query. Slow queries are logged, not stopped. If hard interruption is a requirement, execution needs to move to a worker thread that can be terminated. That is a deliberate trade, not an oversight.
Nothing is read from disk at runtime. The schema is a TypeScript module,
not a .sql file, and there is no native addon. Both are the same lesson: a
bundler tracing a serverless build follows import statements, not paths computed
at runtime, so anything loaded by path is silently dropped and fails on the first
request. Imports cannot go missing.
It needs Node 22.5 or newer. The database driver is node:sqlite, built into the runtime, so there is no native addon to compile and nothing for a bundler to lose while tracing a serverless build. The cost is a version floor and an ExperimentalWarning on stderr.
Masking is not anonymisation. Partial masks preserve enough structure to correlate rows. That is intentional — it is what makes the data still analytically useful — but it means the masking defends against casual exfiltration, not against a determined re-identification attack.
The allowlist is a table allowlist, not a row-level one. There is no per-tenant or per-user scoping. A real deployment against multi-tenant data needs row-level filtering injected into every query, which is a different and larger piece of work.
Confirmation tokens live in process memory. They do not survive a restart and are not shared across replicas. For a single stdio server that is correct; a horizontally scaled HTTP deployment would need shared storage.
Layout
src/
├── constants.ts every safety boundary, in one file
├── db/
│ ├── schema.ts six business tables plus the audit log, as a string
│ ├── connection.ts
│ └── seed.ts deterministic — the same numbers on every machine
├── security/
│ ├── sql-guard.ts AST parsing, allowlist, limit injection
│ ├── pii.ts column-name-keyed masking
│ ├── confirm.ts single-use, argument-bound tokens
│ └── audit.ts
├── services/
│ ├── query.ts plan inspection and execution
│ └── format.ts markdown/JSON rendering, truncation
└── tools/ one file per domain51 tests cover the guard against statement stacking, comment-hidden injection, subquery smuggling, alias confusion, banned functions and limit evasion; the masking against SELECT * and joins; and the confirmation flow against replay, tampering and cross-tool reuse.
npm testLicence
MIT.
Available Tools
8 toolsharbor_customer_360Full customer pictureARead-onlyIdempotent
Everything about one customer in a single call: profile, subscription, recent invoices, open tickets and 90-day usage totals.
Use this instead of four separate queries when a human asks about an account.
Args:
customer_id (string): exact id, format cus_0042
Returns JSON: { "customer": { id, company_name, contact_name, email, country, industry, employee_count, signed_up_at, churned_at, churn_reason, status }, "subscription": { plan, tier, status, seats, mrr_cents, started_at, trial_ends_at, canceled_at } | null, "billing": { invoices_total: number, paid_cents: number, refunded_cents: number, failed_count: number, recent: object[] }, "support": { open_count: number, resolved_count: number, avg_csat: number | null, recent: object[] }, "usage_90d": [ { feature: string, events: number, quantity: number } ] }
Example: "Why is Kestrel Robotics unhappy?" -> find_customer, then this tool; the open tickets and failed invoices usually answer it.
Error: returns an error naming the id if no such customer exists.
Inputs: customer_id (required).
harbor_describe_tableDescribe a Harbor tableARead-onlyIdempotent
Return the column list, types, nullability and primary key for one table.
Args:
table (string): one of customers, subscriptions, plans, invoices, tickets, usage_events
Returns JSON: { "table": string, "note": string, "columns": [ { "name": string, "type": string, "nullable": boolean, "primary_key": boolean, "masked": boolean } ] }
"masked" marks columns whose values are partially redacted on the way out.
Example: use before writing a query that filters on a column you have not seen yet. Error: returns an error listing valid tables if the name is not readable.
Inputs: table (required).
harbor_extend_trialExtend a trialA
Push a trialing subscription's end date out by a number of days. Requires two calls.
Call 1 — omit confirm_token to get a preview and a token. Call 2 — pass the token with identical arguments to apply it.
Args:
customer_id (string): format cus_0042
days (number): 1 to 30
reason (string): 4-200 chars
confirm_token (string, optional)
Returns for preview: { "stage": "preview", "confirm_token": string, "expires_in_seconds": number, "current_trial_ends_at": string, "new_trial_ends_at": string }
Returns for execute: { "stage": "executed", "customer_id": string, "new_trial_ends_at": string }
Refuses when the customer has no subscription, or the subscription is not in 'trialing' status — you cannot start a new trial for a paying or churned account.
Inputs: days (required), reason (required), customer_id (required), confirm_token.
harbor_find_customerFind a customerARead-onlyIdempotent
Search customers by company name, contact name, email or id.
Use this to turn a human's phrasing ("the Kestrel account") into a customer id before calling harbor_customer_360.
Args:
query (string): partial name, partial email, or exact id
limit (number): 1-50, default 10
Returns JSON: { "matches": [ { "id": string, "company_name": string, "contact_name": string, "email": string, "country": string, "status": "active" | "churned", "signed_up_at": string } ], "count": number }
Emails are partially masked. Matching still works on the unmasked value, so searching "priya" finds her even though the response shows "pr***@...".
Returns an empty match list, not an error, when nothing matches.
Inputs: query (required), limit.
harbor_issue_refundIssue a refundADestructive
Refund part or all of a paid invoice. Requires two calls.
Call 1 — omit confirm_token. Returns a preview of exactly what would change, plus a token valid for 5 minutes. Call 2 — pass that token with identical arguments. The refund is written.
Args:
invoice_id (string): exact id, format inv_00123
amount_cents (number): 1 to 50000
reason (string): 4-200 chars, stored in the audit log
confirm_token (string, optional): omit first, then supply
Returns for the preview call: { "stage": "preview", "confirm_token": string, "expires_in_seconds": number, "invoice": { id, customer_id, amount_cents, already_refunded_cents, status }, "would_refund_cents": number, "resulting_refunded_cents": number }
Returns for the execute call: { "stage": "executed", "invoice_id": string, "refunded_cents": number, "total_refunded_cents": number }
Refuses when: the invoice does not exist, is not paid, or the refund would exceed the amount actually charged.
Inputs: reason (required), invoice_id (required), amount_cents (required), confirm_token.
harbor_list_tablesList Harbor tablesARead-onlyIdempotent
List every table an agent may read, with row counts and a one-line note on each.
Call this first when you do not already know the schema. It is cheap and it prevents guessing.
Args: none.
Returns JSON: { "tables": [ { "name": string, "rows": number, "note": string } ], "pii_masked": boolean // true when email/phone/address columns come back partially redacted }
Tables not listed here cannot be queried — harbor_run_query will reject them.
Inputs: no named parameters.
harbor_revenue_summaryRevenue summaryARead-onlyIdempotent
Revenue broken down by month, plan, country or industry.
group_by='month' reads collected revenue from paid invoices, net of refunds. The other groupings read current MRR from live subscriptions, which is a different question — one is history, the other is run-rate.
Args:
group_by ('month' | 'plan' | 'country' | 'industry'): default 'month'
from (string, YYYY-MM-DD, optional): only for group_by='month'
to (string, YYYY-MM-DD, optional): only for group_by='month'
Returns JSON for group_by='month': { "basis": "collected_revenue", "rows": [ { "month": "2026-07", "invoices": number, "gross_cents": number, "refunded_cents": number, "net_cents": number } ], "totals": { "gross_cents": number, "refunded_cents": number, "net_cents": number } }
Returns JSON for the other groupings: { "basis": "current_mrr", "rows": [ { "": string, "customers": number, "mrr_cents": number, "arpa_cents": number } ], "totals": { "customers": number, "mrr_cents": number } }
Examples:
"How much did we collect in Q2?" -> group_by='month', from='2026-04-01', to='2026-06-30'
"Which plan carries most revenue?" -> group_by='plan'
"Where are our customers?" -> group_by='country'
Inputs: to, from, group_by.
harbor_run_queryRun a guarded SQL queryARead-onlyIdempotent
Run a read-only SQL query against the Harbor business database.
Every query is parsed and checked before execution. It will be rejected if it:
is not a SELECT (no INSERT, UPDATE, DELETE, DROP, ATTACH, PRAGMA)
contains more than one statement
touches a table outside: customers, subscriptions, plans, invoices, tickets, usage_events
calls a file or extension function
would scan the whole invoices or usage_events table without an index
A LIMIT is added if you omit one, and lowered if you exceed 500.
Args:
sql (string): one SQLite SELECT statement
limit (number, optional): row cap, 1-500, default 50
response_format ('markdown' | 'json'): default 'markdown'
Returns JSON: { "rows": object[], // result rows, PII columns partially masked "columns": string[], "row_count": number, "tables_read": string[], "limit_applied": number, "limit_adjusted": boolean, // true if we added or lowered your LIMIT "truncated": boolean, // true if the cap was hit and more data exists "masked_columns": string[], "duration_ms": number }
Examples:
"How many customers churned?" -> SELECT COUNT(*) FROM customers WHERE churned_at IS NOT NULL
"Revenue by plan" -> SELECT p.name, SUM(s.mrr_cents) FROM subscriptions s JOIN plans p ON p.id = s.plan_id GROUP BY p.name
Don't use for: changing data. Use harbor_issue_refund or harbor_extend_trial.
Errors are returned with a "How to fix" line. Read it — it names the specific column, table or clause that caused the rejection.
Inputs: sql (required), limit, response_format.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool has a clearly distinct purpose: schema discovery, query execution, customer lookup, customer snapshot, revenue reporting, and write actions. Even the two write tools are unambiguous—one targets invoices, the other targets subscriptions.
All tools share the consistent 'harbor_' prefix and snake_case convention, with most following verb_noun naming (list_tables, describe_table, run_query, find_customer, issue_refund, extend_trial). 'customer_360' and 'revenue_summary' deviate slightly from the verb-first pattern but remain clear and readable.
Eight tools is well within the ideal range and each earns its place. The set covers schema discovery, querying, customer-specific lookups, a 360 view, revenue reporting, and two common business actions without excess.
The tool surface covers the core read/query workflow plus the most needed write operations (refund and trial extension). Minor gaps exist—there are no direct ticket management or subscription modification tools—but the run_query tool can access underlying tables and the 360 view provides recent support/invoice context.
Maintenance
Related MCP Connectors
Hosted SQL Server MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Text-to-SQL MCP server: read-only queries on PostgreSQL, MySQL and SQL Server with your real schema
Guarded MCP server for agent-readable business truth, provenance, readiness, and discovery.
Paid remote MCP for governed database query review, SQL simulation, approvals, and audits.
Related MCP Servers
- AlicenseAqualityBmaintenanceSQL Server MCP server with AST-based query validation, read-only safety, schema exploration, ER diagram generation, and DBA toolkit integration (First Responder Kit, DarlingData, sp_WhoIsActive).128MIT
- AlicenseNot gradedqualityFmaintenanceRead-only MCP server for SQL databases (SQL Server, Postgres, SQLite) with multi-server support and three-layer safety using AST validation and linting.MIT
- AlicenseAqualityDmaintenanceA read-only MCP server for SQL Server that exposes metadata and guarded SELECT queries with PII masking and five-layer guards.5MIT
- AlicenseAqualityDmaintenanceMCP server for running read-only SQL queries across MySQL and PostgreSQL databases with safety guardrails, credentials stored outside source, and support for multiple databases.2MIT