SCP Local

You can run a Local MCP Server that acts as a bridge between AI assistants and e-commerce systems using the Shopper Context Protocol (SCP). It handles secure authorization, data retrieval, endpoint discovery, and token storage so you can safely access customer data with compatible MCP clients like Claude Desktop.

How to use

Use this server with an MCP client to enable SCP-powered data access for AI assistants. You can run the server locally, test against a development endpoint, or deploy a remote instance for production. Practical flows include starting the MCP server, configuring your MCP client to point at it, authorizing access to a merchant, and then querying for orders, loyalty, offers, and preferences. The server ensures each request is authenticated and authorized by the merchant’s SCP server.

Key capabilities you can leverage with your MCP client include discovering SCP endpoints for merchants, authorizing user access via OAuth 2.0 with PKCE, and securely storing encrypted tokens for continued access without re-prompting the user on every request.

How to install

Prerequisites: you need Node.js and npm installed on your machine.

Install or run the MCP server using the recommended npx approach for quick setup without a local install.

# Quick start with npx (no installation required)
npx -y @shoppercontextprotocol/local-mcp-server

Additional setup and troubleshooting

Testing against a local development SCP endpoint is supported by configuring an environment variable in the MCP server run command. This bypasses DNS discovery and directs all requests to your local test server.

# Test endpoint override (example)
SCP_TEST_ENDPOINT=http://localhost:8787/v1 npx -y @shoppercontextprotocol/local-mcp-server

Configuration basics

The server stores configuration in your home directory and includes defaults for DNS resolution, cache behavior, OAuth polling, and timeouts. You can enable a demo mode to point requests to a local demo endpoint during development.

Default local configuration (created on first run) includes DNS resolver, cache TTL, polling intervals, and a demo endpoint.

Security and data handling

All customer data requests are authenticated and authorized by the merchant’s SCP server. Tokens are stored locally in encrypted form to protect sensitive information.

OAuth 2.0 with PKCE is used to securely authorize access to customer accounts. The server provides flows to initiate authorization, handle magic-link delivery, and poll for completion.

Data you can access with SCP endpoints

Once authorized, you can access merchant data via SCP endpoints such as orders, loyalty, offers, and preferences. These endpoints are designed to deliver data in a secure and privacy-conscious manner.

Available tools

scp_authorize

Authorize access to a merchant by starting the OAuth flow and returning authorization status.

scp_check_authorization

Check whether you are currently authorized with a merchant.

scp_revoke_authorization

Revoke existing authorization to a merchant.

scp_discover

Discover the SCP endpoint for a given merchant domain.

scp_get_orders

Fetch the user’s order history from the merchant SCP endpoint.

scp_get_loyalty

Fetch the user’s loyalty points/status from the merchant SCP endpoint.

scp_get_offers

Fetch the user’s active offers or coupons from the merchant SCP endpoint.

scp_get_preferences

Fetch the user’s saved shopping preferences from the merchant SCP endpoint.

scp_get_intents

Fetch the user’s shopping intents from the merchant SCP endpoint.

scp_create_intent

Create a shopping intent based on user goals to tailor results.