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

{
  "mcpServers": {
    "scp": {
      "command": "npx",
      "args": ["-y", "@shoppercontextprotocol/local-mcp-server"]
    }
  }
}

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:

{
  "mcpServers": {
    "scp": {
      "command": "npx",
      "args": ["-y", "@shoppercontextprotocol/local-mcp-server"],
      "env": {
        "SCP_TEST_ENDPOINT": "http://localhost:8787/v1"
      }
    }
  }
}

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

Installation (Alternative)

For development or if you prefer a local installation:

# Install globally
npm install -g @shoppercontextprotocol/local-mcp-server

# Or install locally for development
git clone <repository>
cd local_mcp
npm install
npm run build

Usage

With Claude Desktop (Local Installation)

{
  "mcpServers": {
    "scp": {
      "command": "scp-mcp-server"
    }
  }
}

Or with a local build:

{
  "mcpServers": {
    "scp": {
      "command": "node",
      "args": ["/absolute/path/to/local_mcp/dist/index.js"]
    }
  }
}

Direct Usage

# If installed globally
scp-mcp-server

# Or with local build
npm start

Development

npm run dev    # Watch mode
npm run build  # Production build
npm test       # Run tests

Configuration

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

{
  "dns_resolver": "1.1.1.1",
  "dns_cache_ttl": 86400,
  "poll_interval": 2,
  "max_poll_attempts": 150,
  "token_refresh_threshold": 300,
  "request_timeout": 30000,
  "demo_mode": true,
  "demo_endpoint": "http://localhost:8787/v1"
}

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:

# Direct usage
SCP_TEST_ENDPOINT=http://localhost:8787/v1 scp-mcp-server

# With npx
SCP_TEST_ENDPOINT=http://localhost:8787/v1 npx @shoppercontextprotocol/local-mcp-server

# In Claude Desktop config (see Quick Start section above)

Option 2: Demo Mode Configuration

Edit ~/.scp/config.json:

{
  "demo_mode": true,
  "demo_endpoint": "http://localhost:8787/v1"
}

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:

{
  "demo_mode": false
}

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

Can you help me authorize access to my Boot Barn account? 
My email is customer@example.com

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:

What are my recent Boot Barn orders?

How many loyalty points do I have at Boot Barn?

Do I have any active offers or coupons?

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

Am I authorized with Boot Barn?

Revoke Access

Revoke my Boot Barn authorization

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

1. Claude Desktop starts and reads claude_desktop_config.json
2. Spawns the SCP MCP server (node dist/index.js or npx)
3. Sends initialize request to the server
4. Server responds with:
   - Server info (name, version)
   - Instructions for the LLM
   - Capabilities (tools, resources)
5. Claude reads the instructions and knows:
   ✓ Check authorization first
   ✓ Ask for email when needed
   ✓ Request all scopes upfront
   ✓ Create intents when users express shopping goals
6. Server is ready, Claude is ready with full context
7. User asks: "Show me my orders"
8. Claude follows the instructions:
   - Checks authorization
   - Asks for email if needed
   - Initiates OAuth flow
   - Retrieves and displays orders

Example Instructions Provided

During initialization, Claude receives these instructions:

IMPORTANT WORKFLOW:

1. AUTHORIZATION REQUIRED FIRST
   Before accessing ANY customer data, you MUST authorize with the merchant domain.
   
   Check authorization:
   - scp_check_authorization(domain="acmestore.com")
   
   If not authorized:
   - Ask user: "What email do you use with [Merchant]?"
   - Call: scp_authorize(domain="...", email="...", scopes=[...])
   - Tell user: "Please check your email for a magic link"

2. ACCESSING DATA
   Once authorized, use these tools:
   - scp_get_orders(domain="...") - Order history
   - scp_get_loyalty(domain="...") - Loyalty status
   - scp_get_preferences(domain="...") - Saved preferences
   - scp_get_intents(domain="...") - Shopping intents

3. CREATING INTENTS
   When user expresses a shopping goal, create an intent:
   - scp_create_intent(domain="...", base_intent="...", context={...})

REMEMBER:
✅ ALWAYS check authorization before accessing data
✅ Request comprehensive scopes upfront
✅ Create intents when users express shopping goals
❌ NEVER access data without authorization first

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