@torknetwork/mcp-server

@torknetwork/mcp-server

Official MCP (Model Context Protocol) server for Tork AI Governance Platform.

Part of the TORK Network - AI governance infrastructure for the agentic era.

Installation

Local (stdio — zero latency)

npm install @torknetwork/mcp-server

Remote via Smithery (one-click, browser-compatible)

{
  "mcpServers": {
    "tork-governance": {
      "type": "http",
      "url": "https://server.smithery.ai/@torknetwork/tork-governance"
    }
  }
}

Both methods connect to the same Tork governance API. Local gives you zero-latency stdio. Remote gives you one-click setup and works in browser-based MCP clients.

Available Tools (49 tools)

Core Governance (5 tools)

Tool	Description
tork_scan_pii	Scan text for PII across 50+ types and 13 countries with regional profiles (v1.1)
tork_governed_passthrough	Execute tool calls with full governance checks
tork_check_policy	Check content against governance policies
tork_audit_stats	Get audit statistics for governance events
tork_audit_logs	Query audit logs with filtering

Tool Governance (3 tools)

Tool	Description
tork_register_tool	Register a tool with governance policy
tork_validate_tool_call	Validate a tool call before execution
tork_tool_call_stats	Get statistics on tool calls

HITL - Human-in-the-Loop (10 tools)

Tool	Description
tork_request_approval	Request human approval for an action
tork_approve_action	Approve a pending action
tork_reject_action	Reject a pending action
tork_check_approval	Check approval status
tork_velocity_alert	Check for slicing attack patterns
tork_hitl_check_velocity	Check approver velocity metrics
tork_hitl_create_cooldown	Create a cooldown period
tork_hitl_check_cooldown	Check if in cooldown
tork_hitl_detect_slicing	Detect slicing attacks
tork_hitl_get_config	Get HITL configuration

Memory Integrity (4 tools) - NEW in v1.3.0

Tool	Description
tork_memory_snapshot	Create memory fingerprint for integrity verification
tork_memory_verify	Verify memory against a snapshot
tork_memory_trust_score	Get/calculate trust score for memory
tork_memory_track_modification	Record memory changes for audit

Supply Chain Visibility (5 tools) - NEW in v1.3.0

Tool	Description
tork_supply_chain_register	Register a dependency
tork_supply_chain_deps	Get agent dependencies
tork_supply_chain_verify	Verify a dependency
tork_supply_chain_vulns	Check for vulnerabilities
tork_supply_chain_health	Get supply chain health score

Cost Controls (5 tools) - NEW in v1.3.0

Tool	Description
tork_cost_record	Record a cost transaction
tork_cost_check	Check if spend is allowed within budget
tork_cost_summary	Get spend summary by period
tork_cost_alerts	Get cost alerts and warnings
tork_cost_budget_status	Check budget utilization status

MCP Auditing (4 tools) - NEW in v1.3.0

Tool	Description
tork_mcp_log_call	Log a tool invocation for audit
tork_mcp_get_stats	Get tool usage statistics
tork_mcp_get_alerts	Get MCP alerts and anomalies
tork_mcp_analyze	Run anomaly detection on tool usage

Cloud API Tools (12 tools)

These tools connect to the live Tork Cloud API for centralized governance management. Requires TORK_API_KEY environment variable.

Tool	Description
tork_dashboard	Get dashboard statistics
tork_list_tools	List all registered tools
tork_list_policies	List all governance policies
tork_get_policy	Get a specific policy by name
tork_list_approvals	List pending HITL approval requests
tork_approve	Approve a pending HITL request
tork_deny	Deny a pending HITL request
tork_cloud_audit_logs	Query audit logs with filtering
tork_create_webhook	Create a webhook for notifications
tork_list_webhooks	List all configured webhooks
tork_delete_webhook	Delete a webhook by ID
tork_governance_check	Real-time policy validation

Shared Context (1 tool) - NEW in v1.5.4

Read-only access to the Tork ops handover — how two Claude accounts that share no conversation memory share an understanding of the estate instead. Requires SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY; without them this one tool reports itself unavailable and every other tool is unaffected.

Tool	Description
get_handover	Read a handover document: current (intent), system (script-gathered facts), lessons, or project:<name>

There is no corresponding write tool, by design. Handover rows are written by scripts a human runs on their own machine, so an agent can read the shared history but cannot quietly rewrite what the other account believes.

Tool-call enforcement (fail closed) — changed in v1.6.0

tork_validate_tool_call refuses tools it has no registered policy for. The refusal names the tool:

tool not registered: deploy_to_production

Before v1.6.0 it failed open: an unregistered tool was allowed with the warning "Tool not registered - allowing with warning". Because the tool registry is an in-memory map that starts empty in every new process, every tool was unregistered until something called tork_register_tool in that same process — so the practical default was to permit everything while reporting that the call had been governed.

Register a policy before the tool is used:

tork_register_tool(tool_name: "deploy_to_production", allowed_agents: [...], requires_hitl: true)

Restoring the old behaviour

export TORK_MCP_ALLOW_UNREGISTERED=true    # default: unset = refuse

Only the exact string true enables it. A server started this way prints a loud banner to stderr on startup, because in that mode it is not enforcing tool-call governance.

Where decisions are recorded

Every decision — allow and block — is written to three places:

Destination	What it holds
POST /api/v1/mcp/tool-calls → mcp_tool_calls	The governance decision: policy_evaluated, policy_action, blocked_reason, validation_time_ms, checks performed
POST /api/v1/mcp/audit → mcp_audit_log	The tool invocation detail (unchanged from earlier versions)
POST /api/v1/attestations	The anchored, fingerprinted attestation

The decision row and its attestation share a correlation_id / client_event_id, so they can be joined.

Tool argument names are sent; argument values never are.

If the writer is unreachable, the decision still applies. A block stays a block whether or not the network is up. The unwritten decision is pushed to a bounded in-memory queue and written to stderr, and the tool's own response carries governance_row_written: false with the reason — it is never dropped silently. That queue is process-lifetime only and is a record of what went unwritten, not a retry mechanism; it does not survive a restart.

The gateway executes — changed in v1.6.0

tork_governed_passthrough is the gateway: it decides, and then it runs the tool. Before v1.6.0 its allow branch ended at

{ success: true, message: "Tool call to 'x' validated and would proceed" }

so a caller could not tell a governed execution from a stub, and nothing was ever executed (register item GOV-N13-MCP-GATEWAY-DOES-NOT-ENFORCE).

The policy comes from the database

The gateway reads its policies from public.admin_tools via GET /api/v1/tools — the same rows the admin surface edits. There is no hardcoded list and no in-memory fallback.

If the registry cannot be read, the call is refused, with the read failure as its stated reason. It is never allowed, and it is never decided against a stale snapshot: a cached registry is served only inside its TTL and is dropped, not extended, the moment a refresh fails.

export TORK_MCP_REGISTRY_TTL_MS=30000   # default 30000; 0 disables reuse

tork_register_tool and its in-memory registry are unchanged and still back tork_validate_tool_call, which is an advisory pre-flight check rather than the gateway.

Four outcomes, and why they are four

• outcome: "refused", governed: true — governance said no. reason and blocked_by name the check that fired.
• outcome: "refused", governed: false — governance could not be read. The call was refused, and nothing was recorded as governed: no mcp_tool_calls row and no attestation, because no policy was evaluated.
• outcome: "pending_approval" — a HITL gate fired; no human has decided yet.
• outcome: "executed" — allowed, and the downstream tool ran. result holds that tool's real result.
• outcome: "execution_failed" — allowed, and the tool did not run or ran and failed. blocked is false: this is not a refusal.

outcome is a response discriminator. The governance vocabulary is unchanged — a decision is still only allow / block / flag on the wire and allowed / blocked / flagged / modified in the column.

The same separation holds in the table, so a refusal and a failure are never one ambiguous row:

• policy_action: blocked, status: blocked — we refused it. response_error is null; it was never attempted.
• policy_action: allowed, status: failed — we permitted it and it broke. response_error carries the error.
• policy_action: allowed, status: executed — we permitted it and it ran. executed_at is set.

executed_at is set only when a tool actually ran; a validation-only decision, a block, and a permitted-but-failed call all leave it null. The downstream tool's output is never stored — response_data stays null, for the same reason argument values are never sent.

Reaching the downstream tool

The gateway calls the tool over MCP, using the transport the registry declares for the server that owns it (public.mcp_servers.server_uri / transport_type, read through GET /api/v1/mcp). stdio, http and sse targets are supported. If no downstream can be resolved — no owning server, an unsupported transport, a target that resolves back to this governance server — the call fails; it is never reported as executed.

Embedders that host tools themselves can supply their own executor with setDownstreamExecutor().

Configuration

Set environment variable:

export TORK_API_KEY=your_api_key

Optional — restores the pre-1.6.0 warn-and-allow behaviour for unregistered tools (see above). Default is to refuse:

export TORK_MCP_ALLOW_UNREGISTERED=true

Optional — how long a successfully-read tool registry may be reused by the gateway before it is re-read. A failed re-read always refuses; it never falls back to the previous snapshot:

export TORK_MCP_REGISTRY_TTL_MS=30000

Optional, and only for get_handover:

export SUPABASE_URL=https://<project>.supabase.co
export SUPABASE_SERVICE_ROLE_KEY=<service_role_key>   # full DB access; own the server it runs on

Getting an API Key

• Sign up at tork.network/signup
• Create an account with your email and password
• Your API key will be displayed after signup (save it securely!)
• Set the environment variable: export TORK_API_KEY=tork_live_xxxxx

Usage with Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

Basic (local mode only):

{
  "mcpServers": {
    "tork": {
      "command": "npx",
      "args": ["@torknetwork/mcp-server"]
    }
  }
}

With Cloud API (recommended):

{
  "mcpServers": {
    "tork": {
      "command": "npx",
      "args": ["@torknetwork/mcp-server"],
      "env": {
        "TORK_API_KEY": "tork_live_your_api_key_here"
      }
    }
  }
}

Example Prompts

Once configured, try these prompts with Claude:

Dashboard & Overview:

• "Show me the Tork governance dashboard"
• "List all registered tools in my Tork account"
• "What governance policies do I have configured?"

Memory Integrity (NEW):

• "Create a memory snapshot for agent-prod-1"
• "Verify memory integrity for agent-prod-1"
• "What's the trust score for agent-prod-1's memory?"

Supply Chain (NEW):

• "List dependencies for agent-prod-1"
• "Check for vulnerabilities in my supply chain"
• "Get supply chain health score"

Cost Controls (NEW):

• "Record a $50 transaction for agent-prod-1"
• "Check if agent-prod-1 can spend $100"
• "Show cost summary for this month"

MCP Auditing (NEW):

• "Log this tool call for audit"
• "Show tool usage statistics"
• "Analyze for anomalies in tool usage"

Approvals & HITL:

• "Show me pending approval requests"
• "Approve request tork_abc123 as reviewer [e-mail]"
• "Deny request tork_xyz789 because it targets production"

PII Scanning:

• "Scan this text for PII: Contact [e-mail] at 555-1234"
• "Check if this message contains sensitive data"

Regional PII Detection (v1.1):

• "Scan for UAE PII: Emirates ID 784-1234-1234567-1" (use region: ["ae"])
• "Scan for Indian PII with healthcare patterns" (use region: ["in"], industry: "healthcare")
• Available regions: AU, US, GB, EU, AE, SA, NG, IN, JP, CN, KR, BR
• Available industries: healthcare, finance, legal

Security Features

• Fail Closed: Unregistered tools are refused, not warned about (v1.6.0; opt out with TORK_MCP_ALLOW_UNREGISTERED=true). An unreadable registry refuses too, and is never recorded as a governed decision.
• Durable Decisions: Every allow and block is written to mcp_tool_calls; an unreachable writer never softens a decision
• PII Detection: Automatically scans for and redacts 50+ types of sensitive data
• Blocked Flags: Prevents dangerous flags like --force, --no-confirm, --delete-all
• Rate Limiting: Configurable per-tool rate limits
• Agent Authorization: Control which agents can call which tools
• Target Restrictions: Prevent production access from unauthorized contexts
• HITL Enforcement: Require human approval for sensitive operations
• Fatigue Detection: Lock reviewers who approve too many requests too quickly
• Slicing Attack Detection: Detect patterns of many small requests aggregating to significant impact
• Memory Integrity: Detect unauthorized memory modifications
• Supply Chain Verification: Track and verify all dependencies
• Cost Controls: Enforce budgets and prevent overspending

Links

• Website: https://tork.network
• Documentation: https://docs.tork.network
• GitHub: https://github.com/torkjacobs/tork-governance
• Issues: https://github.com/torkjacobs/tork-governance/issues

License

MIT - see LICENSE