@aura-labs-ai/mcp-server-scout

MCP Server for AURA Scout — Expose purchasing capabilities to Claude and other MCP-compatible AI assistants.

What is this?

This MCP server connects Claude to the AURA commerce protocol. It lets you find products, compare offers from competing suppliers, and commit to purchases — entirely through natural conversation.

Under the hood, the server uses the Scout SDK with Ed25519 cryptographic identity, conversational intent completeness checking, and structured offer evaluation. No API keys, no forms, no portals.

Example conversation:

You: I need noise-cancelling headphones for our office, maybe 20 of them

Claude: A few questions to make sure I find the right options —
        what's your budget, and when do you need them by?

You: Under $8000 total, within two weeks

Claude: Searching for offers...

Claude: I found 3 offers:
1. TechMart — Sony WH-1000XM5 × 20 @ $348 each ($6,960 total) — 5 day delivery
2. AudioPro — Bose QC Ultra × 20 @ $379 each ($7,580 total) — 3 day delivery
3. OfficeBuy — JBL Tour One M2 × 20 @ $299 each ($5,980 total) — 7 day delivery

All within budget. AudioPro has the fastest delivery.

You: Go with AudioPro

Claude: Committed. Transaction TX-abc123 confirmed with AudioPro.

Installation

Claude Desktop

Add to ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "aura-scout": {
      "command": "npx",
      "args": ["@aura-labs-ai/mcp-server-scout"]
    }
  }
}

Restart Claude Desktop. On first launch, the server auto-generates an Ed25519 identity and registers with AURA Core. No API key required.

Claude Code

Add to your project's .mcp.json:

{
  "servers": {
    "aura-scout": {
      "command": "npx",
      "args": ["@aura-labs-ai/mcp-server-scout"]
    }
  }
}

Development

cd sdks/mcp-server-scout
npm install
npm start

Tools

aura_search

Start a new purchasing session with natural language.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | query | string | yes | What you want to buy — be specific about product, quantity, budget, timeline |

Returns needs_clarification (with a question) or searching (with a session_id).

aura_clarify

Provide additional information when aura_search needs clarification.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | session_id | string | yes | Session ID from aura_search | | text | string | yes | User's answer to the clarification question |

aura_get_offers

Retrieve offers from competing suppliers.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | session_id | string | yes | Session ID from aura_search |

Returns structured offers with price, delivery estimate, constraint evaluation, and gap notes.

aura_commit

Commit to a specific offer, initiating the transaction.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | session_id | string | yes | Session containing the offer | | offer_id | string | yes | The offer to commit to |

aura_cancel

Cancel an active session before commitment.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | session_id | string | yes | Session to cancel |

aura_status

Check session or transaction status.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | session_id | string | yes | Session to check |

Configuration

| Variable | Default | Description | |----------|---------|-------------| | AURA_CORE_URL | https://aura-labsai-production.up.railway.app | Core API endpoint | | AURA_KEY_PATH | ~/.aura/keys.json | Persistent Ed25519 key storage path | | AURA_OFFER_TIMEOUT | 30000 | Milliseconds to wait for offers | | AURA_LOG_LEVEL | info | Log verbosity (debug, info, warn, error) |

Security

Key storage: The MCP server auto-detects the best storage for Ed25519 private keys via @aura-labs-ai/sdk-common:

• macOS — Keys stored in the system Keychain (hardware-backed encryption at rest via Secure Enclave on Apple Silicon). Zero native dependencies — uses the security CLI.
• Linux / Windows — Keys stored at ~/.aura/keys.json with 0600 permissions (owner read/write only).

Override with AURA_KEY_PATH env var for custom file path, or pass { type: 'file' } to force file-based storage.

No secrets in config: The MCP server requires no API keys, bearer tokens, or passwords. Identity is purely Ed25519 key-based.

Threat model: The key's blast radius in v1 is limited to session creation and offer commitment. No payment processing occurs (see MCP_SCOUT_SERVER.md NG1). Key rotation and revocation are planned for v2.

Architecture

Claude Desktop / Claude Code
  ↕ MCP Protocol (stdio)
MCP Scout Server (this package)
  ↕ Scout SDK (@aura-labs-ai/scout)
    ↕ KeyManager → createStorage() (Keychain on macOS, File elsewhere)
    ↕ IntentSession (completeness gating)
    ↕ ScoutClient (Ed25519-signed requests)
      ↕ AURA Core API
        ↕ Beacon matching + offer collection

Key design decisions:

• Scout SDK integration — All Core interactions through the SDK. No raw HTTP.
• Ed25519 identity — Auto-generated on first run, persisted via FileStorage. No API keys.
• IntentSession completeness — Vague requests trigger clarification before consuming Core resources.
• In-memory sessions — SessionStore tracks active sessions. Identity persists; session state is ephemeral.

Response Shapes

All tool responses follow consistent structures:

// Success
{ "status": "ok", "data": { ... } }

// Searching (session created, awaiting offers)
{ "status": "searching", "session_id": "..." }

// Needs clarification
{ "status": "needs_clarification", "question": "...", "missing": [...], "round": 1, "session_id": "..." }

// No offers received
{ "status": "no_offers", "message": "..." }

// Error
{ "status": "error", "code": "SESSION_NOT_FOUND", "message": "..." }

Error codes: INVALID_INPUT, SESSION_NOT_FOUND, INVALID_STATE, NETWORK_ERROR, COMMITMENT_FAILED, SESSION_ERROR, SERVER_ERROR.

License

Business Source License 1.1 — See LICENSE for details.