npm package: @lumenstrust/mcp-server
Description: MCP Server for LumenTrust — AI Agent trust, payments & vault on Stellar
Author: LumenTrust
Latest version: 1.2.0

# @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.

[![npm](https://img.shields.io/npm/v/@lumenstrust/mcp-server)](https://www.npmjs.com/package/@lumenstrust/mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

---

## 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](https://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`)

```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:

```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"
      }
    }
  }
}
```

---

### Cursor

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

---

### Windsurf

Add to your Windsurf MCP settings:

```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"
      }
    }
  }
}
```

---

### LangChain / LangGraph (Python)

```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

```bash
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](https://stellar.expert/explorer/testnet)

---

## Links

- **Dashboard**: [lumentrust.coresolution.digital](https://lumentrust.coresolution.digital)
- **API Docs**: [lumentrust.coresolution.digital/docs](https://lumentrust.coresolution.digital/docs)
- **npm**: [@lumenstrust/mcp-server](https://www.npmjs.com/package/@lumenstrust/mcp-server)

---

## License

MIT © LumenTrust