@lumenstrust/mcp-server

MCP Server for LumenTrust — on-chain trust scores, programmable spending vaults, and x402 micropayments for AI agents on the Stellar network.

Give your AI (Claude, GPT, Cursor, LangChain...) the ability to pay for data autonomously using USDC on Stellar, while enforcing spending policies and building a verifiable reputation.

What This Does

Your AI agent gets 6 tools:

| Tool | What it does | |------|-------------| | agentvault_paid_fetch | Calls any x402-paywalled API — auto-pays with USDC if needed | | agentvault_check_score | Checks on-chain trust score (0–100) from Soroban smart contract | | agentvault_get_balance | Checks USDC vault balance | | agentvault_discover | Discovers affordable services from the LumenTrust marketplace | | agentvault_get_history | Views recent payment transactions | | agentvault_vault_status | Checks vault spending policy and daily/weekly limits |

Prerequisites

1. Register your agent at lumentrust.coresolution.digital
2. Get a Stellar keypair (public key starting G..., secret key starting S...)
3. Create a spending vault and deposit USDC via the dashboard

That's it. No additional API keys, no subscriptions.

Quick Start

No installation needed. Use npx directly.

Claude Desktop

Edit: ~/Library/Application Support/Claude/claude_desktop_config.json
(Windows: %APPDATA%\Claude\claude_desktop_config.json)

{
  "mcpServers": {
    "lumentrust": {
      "command": "npx",
      "args": ["-y", "@lumenstrust/mcp-server"],
      "env": {
        "AGENT_ID": "G_YOUR_AGENT_PUBLIC_KEY",
        "AGENT_SECRET_KEY": "S_YOUR_AGENT_SECRET_KEY",
        "API_URL": "https://lumentrust.coresolution.digital/api"
      }
    }
  }
}

Restart Claude Desktop. The 6 LumenTrust tools will appear automatically.

Claude Code

Create .claude/mcp.json in your project root:

{
  "mcpServers": {
    "lumentrust": {
      "command": "npx",
      "args": ["-y", "@lumenstrust/mcp-server"],
      "env": {
        "AGENT_ID": "G_YOUR_AGENT_PUBLIC_KEY",
        "AGENT_SECRET_KEY": "S_YOUR_AGENT_SECRET_KEY",
        "API_URL": "https://lumentrust.coresolution.digital/api"
      }
    }
  }
}

Cursor

Create .cursor/mcp.json in your project root — same config as above.

Windsurf

Add to your Windsurf MCP settings:

{
  "mcpServers": {
    "lumentrust": {
      "command": "npx",
      "args": ["-y", "@lumenstrust/mcp-server"],
      "env": {
        "AGENT_ID": "G_YOUR_AGENT_PUBLIC_KEY",
        "AGENT_SECRET_KEY": "S_YOUR_AGENT_SECRET_KEY",
        "API_URL": "https://lumentrust.coresolution.digital/api"
      }
    }
  }
}

LangChain / LangGraph (Python)

from langchain_mcp_adapters.client import MultiServerMCPClient

client = MultiServerMCPClient({
    "lumentrust": {
        "command": "npx",
        "args": ["-y", "@lumenstrust/mcp-server"],
        "transport": "stdio",
        "env": {
            "AGENT_ID": "G_YOUR_AGENT_PUBLIC_KEY",
            "AGENT_SECRET_KEY": "S_YOUR_AGENT_SECRET_KEY",
            "API_URL": "https://lumentrust.coresolution.digital/api"
        }
    }
})

tools = await client.get_tools()

Direct Node.js

AGENT_ID=G... AGENT_SECRET_KEY=S... API_URL=https://lumentrust.coresolution.digital/api \
  npx @lumenstrust/mcp-server

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | AGENT_ID | Yes | Stellar public key of your agent (G...) | | AGENT_SECRET_KEY | Yes | Stellar secret key of your agent (S...) | | API_URL | No | LumenTrust API base URL (default: https://lumentrust.coresolution.digital/api) |

Tool Reference

agentvault_paid_fetch

Fetch data from an x402-paywalled service. If the service returns 402 Payment Required, the tool automatically signs a USDC transaction on Stellar and retries — the AI never needs to handle payment manually.

Parameters:
  url             (required) URL of the service
  method          GET | POST | PUT  (default: GET)
  body            Request body for POST/PUT
  maxAmountStroops Safety cap in stroops (1 USDC = 10,000,000 stroops)

Example prompt to Claude:

"Get the current weather in Jakarta using LumenTrust"

agentvault_check_score

Returns the agent's on-chain trust score from the Soroban reputation contract.

Score levels: new (0-19) → low (20-34) → neutral (35-54) → good (55-69) → trusted (70-84) → elite (85-100)

Example prompt:

"What is my current LumenTrust trust score?"

agentvault_get_balance

Returns current USDC balance available for spending in the vault.

Example prompt:

"How much USDC do I have left in my vault?"

agentvault_discover

Returns services from the LumenTrust marketplace that the agent can currently afford (filtered by vault balance). Optionally filter by category.

Categories: data, ai, analytics, finance, search, compute, iot, other

Example prompt:

"What services can I afford right now on LumenTrust?"

agentvault_get_history

Returns recent payment transactions with outcomes, amounts, and endpoints.

Example prompt:

"Show me my last 10 LumenTrust transactions"

agentvault_vault_status

Returns full vault status: balance, spending limits, daily/weekly usage, circuit breaker state, whitelist mode.

Example prompt:

"What are my current spending limits and how much have I spent today?"

How Trust Scores Work

Scores are calculated from real transaction history (not manually assigned):

score = 10 (base)
      + 0-60  (success ratio: successfulTxs / totalTxs × 60)
      + 0-20  (volume bonus: log₁₀-scaled USDC volume)
      + 0-10  (consistency: ≥5 txs → +4, ≥20 → +7, ≥50 → +10)
      - 3×disputed_txs

New agents get 2 free trials per service before trust score requirements kick in.

Available Demo Services

These x402 services are live and ready to pay from day one:

| Service | Endpoint | Price | |---------|----------|-------| | Real-Time Weather | /api/weather?lat=X&lon=Y | 0.01 USDC | | AI Text Summarizer | POST /api/summarize | 0.02 USDC | | Statistical Insights | POST /api/insight | 0.05 USDC | | Live Crypto Prices | /api/crypto | 0.01 USDC | | Forex Exchange Rates | /api/forex | 0.01 USDC | | Tech News Headlines | /api/news | 0.02 USDC | | Web Search | /api/search?q=... | 0.03 USDC |

All endpoints at: https://lumentrust.coresolution.digital/demo

Architecture

Claude / LLM
    │
    │ MCP stdio transport
    ▼
@lumenstrust/mcp-server (this package)
    │
    │ HTTPS REST calls
    ▼
LumenTrust API (Express + PostgreSQL)
    │
    ├── Vault policy checks (8 layers)
    ├── Stellar USDC transaction signing
    ├── x402 payment loop (402 → sign → retry)
    └── Trust score recording (Soroban on-chain)

The MCP server is intentionally thin — all complex logic (Stellar signing, vault enforcement, reputation tracking) happens in the LumenTrust API, keeping this package lightweight and dependency-free.

Smart Contracts (Stellar Testnet)

| Contract | ID | |---|---| | Reputation | CCMK53O4WNJVVXWIPNEU2CNWB4U4RLUQ4SEHFWJKH32K27F4ETRA4RND | | Vault | CCRSUFIDHRB4IRZOE2DMPOQYN5DSLHVFBUUBTEA3RSBZDU5MQ2R7FYG6 |

View on Stellar Expert

Links

• Dashboard: lumentrust.coresolution.digital
• API Docs: lumentrust.coresolution.digital/docs
• npm: @lumenstrust/mcp-server

License

MIT © LumenTrust