aura-labs.ai

@aura-labs/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/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/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/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/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.