Ton Blockchain MCP Server API Gateway

Overview

The Ton Blockchain MCP Server API Gateway exposes a Model Context Protocol (MCP) front end for interacting with TON nodes and wallets. It acts as a lightweight gateway that centralizes node access, request routing, and real-time message streaming so clients — web apps, bots, and backend services — can interact with the Ton blockchain without managing direct node connections or full node infrastructure.

By putting an API gateway between your applications and Ton nodes you gain uniform endpoints, API key or token-based access control, request validation, and optional TLS termination. The gateway is particularly useful for teams building finance and wallet apps that need fast, secure node access, consistent transaction submission, and real-time notifications for account events or messages.

Features

• Fast proxying to one or more Ton nodes (load balancing/forwarding)
• REST and WebSocket (MCP stream) endpoints for queries and real-time updates
• Transaction submission and status tracking APIs
• API key / token-based access controls and optional rate limiting
• Configurable TLS termination and reverse-proxy support
• Lightweight, deployable via Docker or as a standalone binary
• Logging and basic observability (request/response metrics)
• Extensible configuration for multiple nodes or sharded access

Installation / Configuration

Quick start using Docker (recommended for evaluation):

1. Run with environment variables

docker run -p 8080:8080 \
  -e MCP_LISTEN_ADDR="0.0.0.0:8080" \
  -e MCP_TON_NODE_URL="https://ton-node.example:443" \
  -e MCP_API_KEY="your_api_key_here" \
  --name ton-mcp \
  ghcr.io/devonmojito/ton-blockchain-mcp:latest

2. Example docker-compose.yml

version: "3.7"
services:
  ton-mcp:
    image: ghcr.io/devonmojito/ton-blockchain-mcp:latest
    ports:
      - "8080:8080"
    environment:
      MCP_LISTEN_ADDR: "0.0.0.0:8080"
      MCP_TON_NODE_URL: "https://ton-node.example:443"
      MCP_API_KEY: "replace-with-your-key"
      MCP_TLS_ENABLED: "false"
    restart: unless-stopped

3. Minimal configuration file (if supported)

listen_addr: "0.0.0.0:8080"
ton_nodes:
  - url: "https://ton-node1.example"
  - url: "https://ton-node2.example"
api_keys:
  - "your_api_key_here"
tls:
  enabled: false

Common environment variables

• MCP_LISTEN_ADDR — address the gateway listens on (default: 0.0.0.0:8080)
• MCP_TON_NODE_URL / TON_NODES — upstream Ton node URL(s)
• MCP_API_KEY / API_KEYS — allowed API key(s) for client access
• MCP_TLS_ENABLED, MCP_TLS_CERT, MCP_TLS_KEY — TLS configuration flags and files
• MCP_RATE_LIMIT — optional per-key rate limit (requests/min)

For production, terminate TLS on a reverse proxy (nginx/Caddy) or enable TLS with provided cert/key paths.

Available Resources

• GitHub repository: https://github.com/devonmojito/ton-blockchain-mcp — source, issues, and releases
• API endpoints (typical)
  • GET /mcp/v1/account/{address} — query account data
  • POST /mcp/v1/sendTransaction — submit signed transaction payload
  • GET /mcp/v1/tx/{hash} — check transaction status
  • WS /mcp/v1/subscribe — real-time stream for account or message events
• Client helpers: examples for curl, Node.js, Python (see repo examples or Postman collection if included)

Table: Common API flows

Use Cases

1. Wallet backend: a hosted wallet service can use the MCP gateway to submit signed transactions, track confirmations, and subscribe to incoming message events for user accounts without connecting each client to a full node.

Example: Submit transaction with curl

curl -X POST https://mcp.example.com/mcp/v1/sendTransaction \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"signedBoc":"<base64_boc>"}'

2. Serverless functions: use the gateway from cloud functions to query balances or broadcast transactions without embedding node credentials or dealing with node lifecycle and connections.

3. Real-time notifications: a trading or DeFi app subscribes to the WebSocket stream to receive immediate updates about account changes or new incoming messages and updates UI or triggers business logic.

WebSocket example (JavaScript):

const ws = new WebSocket("wss://mcp.example.com/mcp/v1/subscribe", {
  headers: { Authorization: "Bearer YOUR_API_KEY" }
});
ws.onmessage = (evt) => console.log("mcp event:", evt.data);

4. Multi-node routing: run the gateway in front of multiple Ton nodes to provide redundancy and simple load distribution for enterprise services.

Security and Best Practices

• Always use TLS for public-facing gateways.
• Restrict API keys by origin and usage where supported.
• Monitor request metrics and enable rate limiting for public endpoints.
• Keep upstream node URLs private and allow the gateway to be the single egress point to nodes.

For complete API reference, operational details, and advanced configuration options, see the repository on GitHub: https://github.com/devonmojito/ton-blockchain-mcp.