TDM MCP Server

Model Context Protocol Server for TDM

Session-state checks for AI agents

Documentation • Quick Start • GitHub • X/Twitter

What is TDM MCP Server?

@tdm/mcp-server is a small MCP stdio server for TDM local session-state checks.

The public GitHub repo for tdm-sdk shows the open contract-facing SDK
surface: https://github.com/ToDealMarket/tdm-sdk

The current tdm-sdk npm beta used by the surrounding TDM docs remains
broader and includes the CLI/operator flows referenced here.

Inside the broader Integration Kit, this package is the reference MCP implementation.
It sits next to:

• thin CLI and signer wrappers
• copy-paste framework examples
• lightweight local integration recipes

████████╗ ██████╗  ███╗   ███╗
╚══██╔══╝ ██╔══██╗ ████╗ ████║
   ██║    ██║  ██║ ██╔████╔██║
   ██║    ██║  ██║ ██║╚██╔╝██║
   ██║    ██████╔╝ ██║ ╚═╝ ██║
   ╚═╝    ╚═════╝  ╚═╝     ╚═╝

TDM CLI [V0.0.2-BETA]
SDK + CLI + MCP
Mode: local-first | Docs: todealmarket.com/docs

What it helps with

The tool helps an agent decide whether it should:

• continue
• ask the user to run tdm connect
• suggest tdm fuel
• suggest tdm sweep

Interactive seller commands in tdm-sdk can now auto-start that one-time
Live TDM setup when the live runtime is still missing. MCP still keeps the
explicit instruction path because an agent should ask the operator before
triggering wallet/browser setup on their behalf.

For human operator flows, tdm connect stores the primary wallet locally.
The current multi-wallet MVP also supports connecting one wallet per supported
network for local signing and network-specific payout setup. During connect,
TDM can attempt a safe default payout sync for the same network when that
network does not already have a saved payout wallet. It does not overwrite an
already saved payout wallet automatically, and
tdm connect --no-sync-payout-wallet keeps connect local-only.

If the account protects new payout destinations with TOTP step-up, the
operator should run:

tdm security totp enroll
tdm security totp verify --method-id <id> --code 123456

tdm security totp enroll opens a local setup page with a QR by default. Use
--no-browser if terminal-only setup is preferred.

It is intentionally local-first:

• reads local TDM credentials and runtime hints
• follows TDM_CREDENTIALS_PATH when explicitly set
• otherwise follows TDM_VAULT or the active vault marker from ~/.tdm/vaults/_active
• does not depend on deprecated treasury balance routes
• can use TDM_REMAINING_USDC and TDM_DUST_TOKENS_DETECTED when the host wants to provide fresh snapshot hints

For operators using named vaults, MCP will read the active/default vault context instead of pretending there is only one global runtime forever.

The vault resolution order is explicit:

• TDM_CREDENTIALS_PATH when you pin one credentials file directly
• otherwise TDM_VAULT
• otherwise the active vault marker from ~/.tdm/vaults/_active
• otherwise the legacy default ~/.tdm/credentials.json

That means one MCP process reads one selected vault contour. It does not merge
agents, wallets, or sessions across multiple vaults.

If that active vault has its own optional runtime allowlist, agents in that
vault inherit the narrower destination policy. If no project or vault
allowlist is configured, MCP keeps the broader flexible runtime posture
instead of assuming deny-by-default.

If the operator wants reusable runtime contours, tdm workspace use <name>
can switch the active vault/storage combination before MCP starts. MCP still
reads local runtime state only; it does not own those runtime workspaces.

Local catalogs and published assets now live next to that same runtime layer in tdm-sdk:

• tdm storage add
• tdm storage import-dir
• tdm storage sync
• tdm storage watch
• tdm storage publish
• tdm workspace
• tdm status
• tdm workspace status

MCP itself does not host or upload those files. It can only help an agent or
operator decide when to suggest the surrounding CLI workflow.

States

• FUELED
• DEPLETED
• UNINITIALIZED

Representative response fields:

• state
• remaining_usdc
• wallet_linked
• dust_tokens_detected
• agent_instructions
• balance_source

Install

npm install @tdm/mcp-server

Global install:

npm install -g @tdm/mcp-server

If you already use tdm-sdk, the simplest path is:

tdm mcp

That SDK command writes a project .mcp.json pointing to the bundled MCP runtime.
The standalone @tdm/mcp-server package itself does not mutate your project config files.

Run

tdm-mcp-server

Bundled SDK path:

tdm mcp serve

Programmatic startup

import { startUltraThinRadarServer } from '@tdm/mcp-server';

await startUltraThinRadarServer();

Example response

{
  "state": "DEPLETED",
  "remaining_usdc": 0,
  "wallet_linked": true,
  "dust_tokens_detected": true,
  "agent_instructions": "Suggest tdm sweep.",
  "balance_source": "runtime_snapshot"
}

Scope

This package is a decision helper for agent runtimes. It is not a wallet manager,
payout tool, or general execution framework.

If you need a live JavaScript gateway integration instead of local state
guidance, use tdm-sdk with makePayable(...), tdm-sdk/authorize,
tdm-sdk/checkout, tdm-sdk/session-tanks, or createGatewayClients(...).

If MCP suggests a recovery path such as tdm sweep, the current SDK routing
behavior behind that suggestion is:

• Solana Jupiter:
  • https://api.jup.ag/swap/v1 when JUPITER_API_KEY is configured
  • https://lite-api.jup.ag/swap/v1 as the compatibility fallback without a key
• Base Odos:
  • https://api.odos.xyz without ODOS_API_KEY
  • https://enterprise-api.odos.xyz with ODOS_API_KEY

The MCP server itself does not hold or manage those API keys; it only points
operators toward the surrounding tdm-sdk workflow.

If you need custom local signing for advanced third-party integrations, use the
experimental tdm signer serve mode from tdm-sdk instead of treating the MCP
server as a transaction executor.

Warning:

• advanced users only
• localhost-only signing surface
• blind signing risk exists
• TDM does not take responsibility for losses caused by compromised local scripts or unsafe third-party integrations in that mode

License

MIT