@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

1. Sign up at tork.network/signup
2. Create an account with your email and password
3. Your API key will be displayed after signup (save it securely!)
4. 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 [email protected]"
• "Deny request tork_xyz789 because it targets production"

PII Scanning:

• "Scan this text for PII: Contact [email protected] 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