Skip to content
Ghostline

ghostline-mcp runs locally over stdio. Use the same build as the CLI. Prepare the channel record and the appropriate wallet with the mainnet quickstart.

Connect your host

Put this shape in Claude Desktop's claude_desktop_config.json or the project's .mcp.json for Claude Code. Replace the paths and the public service key. The MCP host must be able to start the executable and read the files.

{
  "mcpServers": {
    "ghostline": {
      "command": "/absolute/path/to/ghostline-mcp",
      "env": {
        "GHOSTLINE_CHANNEL_FILE": "/private/run/channel.json",
        "GHOSTLINE_WALLET_COOKIE": "/private/payer-wallet/mainnet/.cookie",
        "GHOSTLINE_POLICY_BUDGET": "5000",
        "GHOSTLINE_POLICY_MAX_PER_CALL": "1000",
        "GHOSTLINE_POLICY_VENDOR_HEX": "<service-public-key>"
      }
    }
  }
}

Supply the signing secret through the local server process environment. Give the payer and service servers separate wallet cookies. Keep submit flags unset until you have reviewed the relevant quote. Use a host with elicitation support for human approval rules.

Process settings

SettingRole
GHOSTLINE_CHANNEL_FILEChannel record used by open, close, session creation and file status.
GHOSTLINE_CHANNEL_DIRChannel records for list and accepted-call exports.
GHOSTLINE_WALLET_COOKIECookie for the local wallet daemon performing the operation.
GHOSTLINE_PAYER_SECRETPayer signing secret for paid calls and voucher signing.
GHOSTLINE_CLAIM_SECRETClaim secret for opening when the channel record does not supply its own claim key.
GHOSTLINE_SESSIONExplicit payer session path. Paid calls can also use the channel record's session.
GHOSTLINE_SESSION_DIRDirectory for resolving paid-call sessions by quoted channel id.
GHOSTLINE_OPEN_MAX_FEEReviewed opening fee ceiling in µT.
GHOSTLINE_OPEN_SUBMITSet to 1 to allow opening on-chain.
GHOSTLINE_OPEN_TIMEOUT_SECSWallet open result timeout.
GHOSTLINE_LEDGEROptional service ledger for session status.
GHOSTLINE_EXPIRY_EPOCH, GHOSTLINE_INDEXER_URLOptional status settings when inspecting a session.
GHOSTLINE_SEAL_KEY_ID_FILEWallet signer reference for the service on settle or the payer on refund.
GHOSTLINE_CLOSE_DRY_RUNSet to 1 to quote the close without broadcasting.
GHOSTLINE_CLOSE_SUBMITSet to 1 to allow live close.
GHOSTLINE_CLOSE_MAX_FEEFee cap in µT, covered by the revealed fee balance.
GHOSTLINE_CLOSE_TIMEOUT_SECSWallet close result timeout.
GHOSTLINE_SETTLE_MARGINSettlement window in epochs before expiry.
GHOSTLINE_SETTLE_FORCESet to 1 to settle early while settlement remains eligible.
GHOSTLINE_POLICY_UNSAFEExplicit policy bypass. Leave unset for agent use.

See Spending policy for the policy and audit settings.

Tools

The host discovers each tool's argument schema over MCP. The examples below show the main input and the result to look for.

ToolInputResult
ghostline_call_paid{"url":"http://127.0.0.1:8787/fortune"}HTTP status and body, with payment_required and needs_channel for follow-up.
ghostline_sign_voucherPublic channel parameters and a priceHex-encoded voucher from the configured session.
ghostline_open_channel{}Open quote or submitted open, according to the server settings.
ghostline_close_channel{}Wait, settle, refund, or spent output, with dry-run or submission details when applicable.
ghostline_channel_session{}Creates or reuses the file's payer session.
ghostline_channel_status{} for configured defaultsOff-chain totals and available observer/status fields.
ghostline_channel_list{}One row per channel file in the configured directory.
ghostline_channel_calls{}Accepted-call rows from the directory's ledgers.
ghostline_channel_file{}Totals, expiry window and available output presence for the configured record.
ghostline_channel_idPublic open parametersChannel id as hex.
ghostline_verify_voucherChannel parameters and voucher hex{"ok":true} if verification succeeds.
ghostline_inspect_txSealed transaction hexPublic stealth-output fields.
ghostline_unblind_txSealed transaction hexValue and mask for matching outputs. Keep results private.

Walk through run 5

On 13 Nov 2026 the payer server quoted ghostline_open_channel {} and submitted after the operator enabled GHOSTLINE_OPEN_SUBMIT=1. Five calls at 1,000 µT succeeded. The sixth exceeded the 5,000 µT policy budget. The service server used its own wallet cookie and signer with ghostline_close_channel {} to settle. The finalized settlement paid 28,808 µT in network fees.

Follow the mainnet agent walkthrough for the exact sequence and view the open and settle records under Mainnet proof.