SCP Local MCP Server

A Model Context Protocol (MCP) server that provides AI assistants like Claude with secure access to customer data through the Shopper Context Protocol (SCP).

What is this?

This MCP server acts as a bridge between AI assistants and e-commerce systems that implement the SCP protocol. It enables Claude Desktop and other MCP clients to:

• 🔐 Securely authorize access to customer accounts using OAuth 2.0 with PKCE

• 📦 Retrieve order history, loyalty points, active offers, and shopping preferences

• 🔍 Discover SCP endpoints for merchants via DNS or well-known URIs

• 🔒 Store and manage encrypted authentication tokens locally

All customer data requests are authenticated and authorized by the merchant's SCP server, ensuring privacy and security.

Quick Start with npx

The easiest way to use this server is with npx - no installation required!

With Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

On Windows, the config file is located at: %APPDATA%\Claude\claude_desktop_config.json

Testing with a Local Development Server

If you're developing an SCP server locally, you can configure the MCP server to point to your test endpoint:

This bypasses DNS discovery and directs all requests to your local test server.

Installation (Alternative)

For development or if you prefer a local installation:

Usage

With Claude Desktop (Local Installation)

Or with a local build:

Direct Usage

Development

Configuration

The server stores configuration in ~/.scp/config.json. It will be created automatically on first run with these defaults:

Configuration Options

• dns_resolver: DNS server to use for SCP endpoint discovery (default: Cloudflare's 1.1.1.1)

• dns_cache_ttl: How long to cache discovered endpoints in seconds (default: 24 hours)

• poll_interval: Seconds between polling attempts during OAuth flow (default: 2)

• max_poll_attempts: Maximum number of polling attempts (default: 150 / 5 minutes)

• token_refresh_threshold: Seconds before expiry to refresh tokens (default: 300 / 5 minutes)

• request_timeout: HTTP request timeout in milliseconds (default: 30000 / 30 seconds)

• demo_mode: Enable demo mode (default: true)

• demo_endpoint: Endpoint to use in demo mode (default: http://localhost:8787/v1)

Testing with a Development Server

There are multiple ways to point the MCP server to your test SCP server:

Option 1: Environment Variable (Recommended for npx)

Set SCP_TEST_ENDPOINT when running the server:

Option 2: Demo Mode Configuration

Edit ~/.scp/config.json:

By default, demo mode is enabled and directs all SCP requests to the demo endpoint. This is useful for local testing without needing DNS records.

Option 3: Production Mode

To use real DNS-based discovery for production merchants:

Priority Order:

1. SCP_TEST_ENDPOINT environment variable (highest priority)

2. Demo mode configuration

3. DNS-based discovery (lowest priority)

Data Storage

• Tokens: ~/.scp/tokens.db (SQLite, encrypted)

• Config: ~/.scp/config.json

MCP Tools

• scp_authorize - Authorize access to a merchant

• scp_check_authorization - Check authorization status

• scp_revoke_authorization - Revoke access to a merchant

• scp_discover - Discover SCP endpoint for a domain

MCP Resources

• scp://{domain}/orders - Order history

• scp://{domain}/loyalty - Loyalty status

• scp://{domain}/offers - Active offers

• scp://{domain}/preferences - Customer preferences

• scp://{domain}/intents - Shopping intents

How to Use in Claude Desktop

After adding the MCP server to your Claude Desktop config and restarting Claude, you can interact with SCP-enabled merchants:

First Time: Authorize Access

Claude will use the scp_authorize tool to:

1. Discover the SCP endpoint for bootbarn.com

2. Initiate OAuth authorization with a magic link

3. The magic link will be sent to your email

4. Poll for authorization completion

5. Store encrypted tokens locally

Access Your Data

Once authorized, you can ask Claude to retrieve your data:

Claude will automatically:

• Use the stored authorization tokens

• Refresh tokens if they're about to expire

• Fetch data from the merchant's SCP server

• Present the information in a helpful format

Check Authorization Status

Revoke Access

Example Workflow

Here's a complete example of using SCP in Claude Desktop:

You: "Help me authorize with acmestore.com using customer@example.com"

Claude: Initiates OAuth flow, sends magic link to email

You: Clicks magic link in email

Claude: Completes authorization and confirms success

You: "What orders have I placed?"

Claude: Retrieves and displays order history

You: "Do I have any active coupons?"

Claude: Shows available offers and promotions

How It Works: Initialization Instructions

The SCP MCP Server provides built-in instructions to Claude during the initialization phase, ensuring it knows how to properly use the SCP tools without any additional prompting.

Automatic Guidance

When Claude Desktop connects to the SCP server, it automatically receives instructions that tell it to:

1. Always check authorization first - Before accessing any customer data, Claude will check if you're authorized with the merchant

2. Ask for your email - If not authorized, Claude will ask for your email address to start the OAuth flow

3. Request all necessary scopes - Claude requests comprehensive permissions upfront: orders, loyalty, preferences, intent:read, intent:create

4. Explain the magic link process - Claude tells you to check your email for the authorization link

5. Handle errors gracefully - If something goes wrong, Claude knows how to guide you through fixing it

Why This Matters

This automatic initialization means:

• ✅ No manual configuration needed - Claude knows how to use SCP tools immediately

• ✅ Consistent behavior - Every conversation follows the same authorization workflow

• ✅ Better user experience - Claude proactively handles authorization before trying to access data

• ✅ Fewer errors - Reduces "Not authorized" errors by checking authorization first

The Initialization Flow

Example Instructions Provided

During initialization, Claude receives these instructions:

This ensures every interaction with the SCP server follows best practices and provides a smooth, secure experience for users.