ScrymeDeveloper Docs
Model Context Protocol (MCP)

Connect intelligent AI assistants directly to your workspace

The Model Context Protocol gives external AI tools such as Claude Desktop, Cursor, Claude Code, and custom autonomous agents safe, real time access to your Scryme platform. You can query stock counts, inspect sales analytics, examine schedules, stage safe database modifications through tenant isolated endpoints, and execute changes with full audit trails.

Live Workspace Data

Query products, stock batches, orders, customer profiles, and financial aggregates directly without manual data exports.

Strict Tenant Isolation

Every read and write operation is scoped strictly to your organization ID, ensuring complete isolation and zero cross tenant leakage.

Safe Draft Lifecycle

AI updates are staged as reviewable drafts with diff summaries, atomic commit confirmations, and safe snapshot rollback.

Transport protocols and connection choices

Scryme supports two primary connection methods defined by the open Model Context Protocol specification:

Stdio CLI Transport

Best for workstation applications such as Claude Desktop, Cursor, and Claude Code. The client spawns our lightweight command line runner via npx or pnpm, communicating over standard input and output streams.

npx -y @scryme/mcp-server
Streamable HTTP Transport

Best for cloud agents, remote server environments, and web applications. The client connects directly to our modern Streamable HTTP endpoint supporting keep alive streaming, session tracking, and JSON-RPC 2.0 messages over HTTP POST.

https://api.scryme.tech/v3/mcp

Authentication mechanisms and credentials

Before connecting any AI tool, your client must present valid credentials. Scryme provides three flexible authentication pathways:

1. Dedicated MCP API Keys (Recommended):

Generate keys starting with mcp_live_ inside the web portal at /integrations/mcp. The server stores only cryptographic SHA-256 hashes, keeping your credentials secure. Pass via Authorization: Bearer <key>, the x-mcp-api-key header, or the ?key= query parameter.

2. BetterAuth OAuth 2.0 Access Tokens:

OAuth clients and user sessions can authenticate using BetterAuth access tokens with scopes mcp:read and mcp:write. The server automatically associates requests with the user active organization.

3. HS256 JWT Bearer Tokens:

For custom agent pipelines, you can provide an HS256 signed JSON Web Token holding the organizationId claim along with mcp:read and mcp:write scopes.

OAuth 2.0 discovery and RFC 9728 metadata

The Scryme MCP endpoint implements RFC 9728 OAuth 2.0 Protected Resource Metadata. When an unauthenticated request arrives, the server returns an informative 401 challenge header indicating discovery locations:

RFC 9728 Protected Resource Probe
curl -i -X GET "https://api.scryme.tech/v3/mcp"

# Response:
# HTTP/1.1 401 Unauthorized
# WWW-Authenticate: Bearer resource_metadata="https://api.scryme.tech/.well-known/oauth-protected-resource/v3/mcp"

# Fetching resource metadata:
curl -s "https://api.scryme.tech/.well-known/oauth-protected-resource/v3/mcp"

Client setup and configuration files

Here are ready to use snippets for popular AI client platforms. Replace mcp_live_your_workspace_key_here with the token created in your workspace settings.

Claude Desktop (claude_desktop_config.json)
{
  "mcpServers": {
    "scryme": {
      "command": "npx",
      "args": ["-y", "@scryme/mcp-server"],
      "env": {
        "SCRYME_API_KEY": "mcp_live_your_workspace_key_here",
        "SCRYME_API_URL": "https://api.scryme.tech"
      }
    }
  }
}

Locate this file on macOS at ~/Library/Application Support/Claude/claude_desktop_config.json or on Windows at %APPDATA%\Claude\claude_desktop_config.json.

Cursor IDE (.cursor/mcp.json)
{
  "mcpServers": {
    "scryme": {
      "command": "npx",
      "args": ["-y", "@scryme/mcp-server"],
      "env": {
        "SCRYME_API_KEY": "mcp_live_your_workspace_key_here",
        "SCRYME_API_URL": "https://api.scryme.tech"
      }
    }
  }
}
Claude Code CLI Command
claude mcp add scryme -- npx -y @scryme/mcp-server
Streamable HTTP Endpoint Configuration
{
  "mcpServers": {
    "scryme-remote": {
      "url": "https://api.scryme.tech/v3/mcp",
      "headers": {
        "Authorization": "Bearer mcp_live_your_workspace_key_here"
      }
    }
  }
}
JSON-RPC 2.0 Call with Session Tracking
curl -X POST "https://api.scryme.tech/v3/mcp" \
  -H "Authorization: Bearer mcp_live_your_workspace_key_here" \
  -H "Content-Type: application/json" \
  -H "mcp-session-id: sess_01hxyzexample" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_sales_analytics",
      "arguments": {
        "timeframe": "month"
      }
    }
  }'
Direct HTTP Tool Execution
curl -X POST "https://api.scryme.tech/v3/mcp/tools/execute" \
  -H "Authorization: Bearer mcp_live_your_workspace_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "query_inventory",
    "arguments": {
      "search": "espresso",
      "limit": 5
    }
  }'

The staged draft lifecycle and change safety

Allowing automated models to alter products, create sales records, or reassign shifts requires strong guardrails. Scryme implements a two phase staged mutation pattern:

1. Stage DraftTool proposes changes and records initial state snapshot.
2. Review DiffInspect field level diff summary with get_draft_diff.
3. Apply AtomicallyRun publish_draft with confirm true in an ACID transaction.
4. Safe RollbackUse revert_draft anytime to restore initial snapshot state.

Note: For trusted automated tasks, tools also accept an optional parameter autoPublish: true to stage and publish changes immediately in one roundtrip.

Standard MCP resources

In addition to callable tools, Scryme exposes standardized MCP resources for context aggregation:

scryme://analytics/summaryapplication/json

Sales and Financial Summary

Live revenue totals, order counts, gross and net values, and key financial performance indicators for the active month.

scryme://inventory/summaryapplication/json

Inventory Overview

Summary of product catalog variant stock quantities, location breakdown, and low stock items.

Complete catalog of MCP tools (23 tools)

External assistants have access to the following workspace tools. Each tool strictly honors your organization boundary and member permissions:

Inventory and Catalog Read Tools

query_inventory

Inspect variant stock counts, batch allocations, and quantities across physical locations.

Inputs: search (string), locationId (string), limit (number)
search_products

Query product catalog records with category filters, barcode matches, and pricing profiles.

Inputs: query (string), categoryId (string), limit (number)

Sales, Orders, and Analytics Tools

list_orders

Search transactions and sales orders filtered by status, customer, or creation date range.

Inputs: status (string), customerId (string), startDate (string), endDate (string), limit (number)
get_order_details

Retrieve the complete line item breakdown, payments, and fulfillment records for an order.

Inputs: transactionId (string, required)
search_customers

Locate customer contact details, profile information, and accumulated loyalty points.

Inputs: query (string), limit (number)
get_sales_analytics

Calculate gross revenue, net revenue, tax aggregates, and average order value for a timeframe.

Inputs: timeframe ("today" | "week" | "month" | "year")
get_top_selling_products

Rank highest performing products based on total sales volume and overall revenue.

Inputs: limit (number)

Staff and Operations Tools

list_staff_tasks

Review team assignments, priority ratings, due dates, and progress states.

Inputs: status (string), assignedMemberId (string), limit (number)
get_shift_schedules

Retrieve scheduled employee shifts and active workspace attendance for any date.

Inputs: date (string), locationId (string)

Draft Management and Change Staging Tools

list_drafts

Inspect staged drafts, proposed changes, review statuses, and target entities.

Inputs: status (DRAFT | APPLIED | REVERTED | DISCARDED), entityType (PRODUCT | PRICE | ORDER | FULFILLMENT | STAFF_TASK), limit (number)
get_draft_diff

Examine field level before and after diff comparisons prior to applying mutations live.

Inputs: draftId (string, required)
publish_draft

Commit a staged draft change directly into the database inside an ACID transaction.

Inputs: draftId (string, required), confirm (boolean, required)
revert_draft

Roll back an applied draft change cleanly using its recorded before state snapshot.

Inputs: draftId (string, required), confirm (boolean, required)
discard_draft

Drop an unapplied draft change safely without affecting any live workspace tables.

Inputs: draftId (string, required)

Product Catalog Staged Mutations

create_product

Stage creation of a new catalog product with SKU, category, name, and initial variants.

Inputs: name (required), sku, categoryId, description, barcode, variants, autoPublish (boolean)
update_product

Stage updates to product catalog attributes such as name, description, status, or category.

Inputs: productId (required), name, description, categoryId, isActive, autoPublish (boolean)
update_product_price

Stage modifications to variant retail price, wholesale price, or buying cost.

Inputs: variantId (required), retailPrice, wholesalePrice, buyingPrice, autoPublish (boolean)

Orders and Fulfillment Staged Mutations

create_order

Stage a customer transaction with line items, unit pricing, notes, and fulfillment location.

Inputs: locationId (required), items (required), customerId, notes, autoPublish (boolean)
update_order_status

Transition transaction status with full event tracking across the workspace lifecycle.

Inputs: transactionId (required), status (required), autoPublish (boolean)
fulfill_order

Stage or record order fulfillment with tracking number, courier service, and dispatch status.

Inputs: transactionId (required), trackingNumber, carrier, status, autoPublish (boolean)

Staff Task Assignment Staged Mutations

create_staff_task

Assign operational responsibilities, priorities, and deadlines to workspace members.

Inputs: title (required), description, priority, dueDate, memberId, locationId, autoPublish (boolean)
assign_staff_task

Stage reassignment of an existing staff task to another workspace staff member.

Inputs: taskId (required), memberId (required), autoPublish (boolean)
update_staff_task_status

Stage or update task progression (TODO, IN_PROGRESS, COMPLETED, CANCELLED).

Inputs: taskId (required), status (required), autoPublish (boolean)