sentineltx-mcp
v2.0.1
Published
SentinelTX MCP Server — Blockchain forensic intelligence tools for Claude
Maintainers
Readme
sentineltx-mcp
Blockchain forensic intelligence tools for Claude via MCP (Model Context Protocol).
Trace stolen crypto, detect cross-chain bridges, identify exchanges, and analyze risk across Ethereum and 50+ other EVM chains, Bitcoin, Litecoin, Solana, Tron and XRP — directly from Claude.
Quick Start
Version 2 requires Node.js 20 or later. Upgrade Node before updating a Node 18 installation. The major version marks this runtime change; the patched HTTP adapter dependency no longer supports Node 18. The connector still uses stdio and does not open an HTTP listener. Runtime JavaScript is readable; private server sources, source maps, tests and internal documents are not shipped. The release carries a production dependency lock and checks the resolved security versions before starting. If an existing project's dependency tree conflicts, install this version in a clean, isolated npm environment. Do not bypass the check.
npx [email protected]Setup
1. Get an API Key
Sign in to SentinelTX, open My Page → MCP · API, and issue a new key.
Your plan must include MCP. Version 2 uses keys beginning stx_mcp2_ with the
exclusive mcp_v2 scope. They expire after 90 days and can be revoked on that
page. The full key is shown once; only a hash is stored on the server.
All 0.x and 1.x releases are retired. Existing keys, including old admin keys, do not automatically gain access to v2. A new key does not reopen the old API paths. The connector never falls back to the retired API.
Partners specifically approved by SentinelTX may keep their existing partner
key with 2.0.1 or later: set SENTINELTX_API_KEY to that key and
SENTINELTX_MCP_PARTNER_MODE=1. Approval is recorded against that individual
key on the server; setting the environment variable alone grants no access.
Use the same stdio configuration below with this additional environment
variable. Account ownership, tenant isolation, revocation and billing still
apply. Unapproved keys must use the normal My Page issuance flow.
The seven investigation tools use /api/v2/mcp/. Their sessions, ownership
checks and billing are the same as in the workspace. Official report tools
still require a separate interactive owner credential and user attestation;
the MCP key cannot compile or download those reports on its own.
2. Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"sentineltx": {
"command": "npx",
"args": ["-y", "[email protected]"],
"env": {
"SENTINELTX_API_KEY": "stx_mcp2_your_new_key_here"
}
}
}
}3. Claude Code
claude mcp add sentineltx -e SENTINELTX_API_KEY=stx_mcp2_your_new_key_here -- npx -y [email protected]Tools
The connector provides seven investigation tools and four official-report tools.
| Tool | Description |
|------|-------------|
| lookup_address | Labels, risk tags, entity, balance and up to five top outbound counterparties for one address, as a short fact table. The counterparties come from a five-hop trace, so some may not be direct. A live analysis, ceiling 90s; a timeout returns a session_id to collect the answer with check_investigation. |
| validate_address | Address format validation and chain detection. One request. |
| check_credits | Remaining investigation credits. |
| start_investigation | Begin a forensic trace, or continue a lookup's case with its session_id for the court-grade write-up. Returns a session_id at once; the trace runs server-side, most within 10 minutes, a court-grade report 40 minutes or more. |
| check_investigation | Poll a session_id until its status is final. Long-polls, so one call can take up to wait_sec + ~28s (≈73s at the default). |
| cancel_investigation | Abort a running investigation. Idempotent. |
| get_investigation_graph | Fund-flow graph (nodes + links) saved for an investigation, as a share URL, or as inlined JSON up to 64K characters (a larger graph returns its counts, size and the URL; a failed fetch returns the URL and the reason). A run that stopped short exports what it traced before it stopped, and its investigation_status line (anything but complete) marks the graph as partial. |
| get_official_report_draft | Read the production canonical draft for user review. Requires an interactive user credential; this is not a finished artifact. |
| generate_official_report | Compile an already user-attested case through production /reports/generate, preserving its evidence and entitlement gates. PDF or DOCX, with a persisted idempotency key. |
| check_official_report | Recover the same owned compile job after a timeout, using its original session and key. No new compile. |
| download_official_report | Save the production artifact and its attestation/receipt after checking case binding, SHA-256 and byte length. Never re-renders the report locally. |
The second group is asynchronous on purpose: the trace outlives any single
request, so start_investigation hands back an id and the trace runs
server-side, apart from the polls, and saves its answer to the case whether or
not anything is polling it. Call check_investigation back to back until its
status is complete, error, cancelled, continuation_required or continuation_unavailable; a gap between calls loses nothing, since
the next call returns what the run saved. A failed or abandoned check_investigation
call says nothing about the investigation itself, and the tool's output says so
rather than reporting the case as dead. A start_investigation that gets no
answer is the opposite case: it may have opened, and charged for, its
investigation anyway, so it is never resent, and its error says to check the
dashboard before calling it again.
Continuing a long investigation
Long investigations may return continuation_required instead of complete.
Use the returned successor as session_id and its parent as continuation_from
in start_investigation. The connector reads the owned parent's bounded handoff
and carries the original question and transaction references into the next turn.
Prior notes remain unverified until re-anchored; private reasoning is not carried.
If the server supplies no successor, continuation_unavailable names the saved
case without claiming a final report. A continuation may use analysis credits.
Official reports: production compiler, presentation differences
Investigation text and a graph are not a sealed PDF/DOCX. The four report tools call the workspace's existing canonical-draft, compile, job and download routes. They do not create a separate report template or author a replacement narrative. These tools preserve production refusals for missing attestation, locked encrypted cases, unavailable evidence and missing detailed-report access. Credentials and signed-link capabilities are redacted at the tool output boundary, including failures inside HTTP 200 responses. If this affects draft text, the output explicitly says to review the original in the workspace before attesting.
This is not yet identical to a workspace-configured report. The connector
explicitly sends the web defaults: confidentiality: "confidential",
case_type: "Cryptocurrency Investigation", graph_placement: "appendix",
brand: "Sentinel", and include_graph: true. Confidentiality is selectable:
public, internal, confidential, or restricted. The server still chooses
the tenant's brand and author and derives the canonical case reference.
The connector does not import your edited executive summary or saved canvas selections. The server may derive different summary text and figures. Every report result includes this limitation; use the workspace to compile the exact summary and figures you reviewed there.
The production compile route deliberately rejects integration API keys. Supply
SENTINELTX_USER_ACCESS_TOKEN from a trusted local launcher with an authenticated
case-owner session. Never put the JWT in MCP config files: Desktop JSON
env entries and claude mcp add -e SENTINELTX_USER_ACCESS_TOKEN=... persist it
as plaintext. Do not put it in prompts, shell history, source control, issues
or command-line arguments either. The connector does not read browser cookies, sign users in, refresh
sessions or change API-key permissions. When the credential expires, renew it
through your interactive sign-in flow and restart the connector. An API key
continues to be used only by the seven investigation tools.
The connector does not implement interactive login or credential refresh. Use a trusted local sign-in launcher to inject the owner's current session through the process environment. Configure MCP with that launcher's path; never store a JWT in MCP configuration or command arguments. Restart after interactive renewal.
- Complete the investigation; read its canonical draft with
get_official_report_draft. The user reviews and attests per report in the workspace. Case unlock and any zero-access retention consent remain separate user actions. A paid-access refusal requires the user's decision. - Persist a unique
idempotency_keywith the case and output format beforegenerate_official_report. The title, format and confidentiality are presentation options; the server selects the attested narrative. Production may email the artifact to its owner as it does for a workspace compile. - If a call times out, use
check_official_reportwith the same session and key. No automatic POST retry, new key or duplicate charge. A 404/503 from polling does not prove that a compile never started. - On
ready, calldownload_official_report. It savesreport.pdforreport.docx,attestation.jsonandreceipt.jsonin a new private directory underSENTINELTX_REPORT_DIR. Signed links remain inside the connector; redirects and foreign-origin downloads are refused. Files above 50 MiB require the workspace download. This GET starts production's first-delivery purge grace. A later web Save may return 404 after purge. Retain the local artifact, sidecar and receipt securely; a successful compile is not a permanent download store.
Only state=downloaded confirms delivery with a matching artifact digest. This
is a local delivery receipt, not a server custody event or independent
public-key signature verification: the production download route verifies the
artifact's signature, while this client checks the delivered bytes against the
server manifest. Unlike web Save, MCP does not append the workspace's server
audit/custody event (server_custody_recorded: false). Use the workspace when
that workflow is required; no tool fabricates human attestation or a custody
record. MCP therefore does not claim full web delivery-workflow parity.
A batch must track investigation completion, user review,
compile state and artifact delivery separately. Completed investigations do not imply approved reports; missing seeds and failed integrity gates stay visible.
Examples
Once configured, just ask Claude:
- "Trace 0x1234... on Ethereum — where did the funds end up?"
- "Who sent funds to this Bitcoin address?"
- "Did this TRON address move anything across a bridge?"
- "Is 0xdead... a known exchange?"
- "Check my remaining credits"
Claude picks the tools. Fund-flow tracing, bridge detection and exchange
attribution are all work start_investigation does inside one investigation —
there is no separate tool to call for each, which is why asking in plain
language works better than naming a tool.
Supported Chains
Ethereum and 50+ other EVM chains (BSC, Polygon, Arbitrum, Optimism, Base, Avalanche, …), Bitcoin, Litecoin, Solana, Tron and XRP.
Environment Variables
| Variable | Description |
|----------|-------------|
| SENTINELTX_API_KEY | New MCP v2 key from My Page; legacy keys are refused locally |
| SENTINELTX_USER_ACCESS_TOKEN | Interactive case-owner credential for official-report tools; never passed as a tool argument |
| SENTINELTX_REPORT_DIR | Private artifact output directory (default: ~/Downloads/SentinelTXReports) |
| SENTINELTX_API_URL | API base URL (default: https://api.sentineltx.ai) |
| SENTINELTX_APP_URL | Dashboard base URL used in the links tools return (default: https://app.sentineltx.ai) |
License
MIT
