AI Assistant Connection (MCP)

Connect AI assistants like Claude directly to StoreOps — review monthly reports, look up ledger entries, record expenses, and create materials, all through chat. What the AI can do is always a subset of what you can do, and every action it completes is written to the audit log.

How it works

• The connection token (a long string starting with sop_) is the AI assistant's key, bound to this store + the person who created it.
• When you create one, you choose whether it can write, its role ceiling, and when it expires (90 days by default). What the AI can actually do is the intersection of your current role, the token's read/write scopes, and its role ceiling — the smallest of the three wins.
• Lose a role later and the token shrinks with you; gain one and the token does not grow.
• Deleting entries, closing days, closing months and settling payouts are web-only — the AI is refused even with a write-enabled token.
• The token is not your password — revoke and regenerate it anytime without affecting your login.

Creating a token

1. Go to Settings → Integrations and find the AI Assistant Connection section (requires manager or above).
2. Enter a label so you can tell tokens apart later (e.g. "Claude on the manager's laptop").
3. Choose what it can do: tick only "read data" for a read-only token — the AI can look but not change anything.
4. Choose the role ceiling: you can only go up to your own role. For a trial, "staff" is the safe pick.
5. Choose the expiry: 90 days by default, or a custom number of days, or "permanent". Tokens nearing expiry are flagged for rotation in the list.
6. Click Create token. The token is shown only once — copy it (or the ready-made connect command) right away.
7. Lost it? No problem: revoke the old one and create a new one. Up to 50 tokens per store.

Connection methods at a glance

Your tool	How to connect
Claude Code (terminal)	One command — the "Copy connect command" button gives it to you verbatim
Claude web / desktop / mobile	Custom connector — see Connecting from Claude on the web
Codex CLI	Command + environment variable
Hermes	config.yaml
Cursor, opencode, other MCP-capable tools	Config file (URL + Authorization header)
ChatGPT	Not supported yet: its custom connectors only allow OAuth / no-auth, so a fixed token can't be used

Per-tool setup

Replace https://your-storeops-url with your actual StoreOps address and sop_your-token with the token you created.

Claude Code

claude mcp add --transport http storeops https://your-storeops-url/api/mcp \
  --header "Authorization: Bearer sop_your-token"

# Run /mcp inside Claude Code afterwards to check the connection

Codex CLI

# Codex reads the token from an environment variable
# (put the export in ~/.bashrc or ~/.zshrc)
export STOREOPS_MCP_TOKEN="sop_your-token"

codex mcp add storeops \
  --url https://your-storeops-url/api/mcp \
  --bearer-token-env-var STOREOPS_MCP_TOKEN

Hermes

# ~/.hermes/config.yaml
mcp_servers:
  storeops:
    url: https://your-storeops-url/api/mcp
    headers:
      Authorization: Bearer sop_your-token

Cursor

// ~/.cursor/mcp.json (global) or .cursor/mcp.json in a project
{
  "mcpServers": {
    "storeops": {
      "url": "https://your-storeops-url/api/mcp",
      "headers": { "Authorization": "Bearer sop_your-token" }
    }
  }
}

opencode

// opencode.json
{
  "mcp": {
    "storeops": {
      "type": "remote",
      "url": "https://your-storeops-url/api/mcp",
      "headers": { "Authorization": "Bearer sop_your-token" }
    }
  }
}

The general rule

Any tool that supports a remote/HTTP MCP server with custom headers can connect: point it at https://your-storeops-url/api/mcp and add the header Authorization: Bearer sop_your-token.

What you can ask the AI to do

Once connected, just chat:

• "Review the August report and compare it with July" (there's also a built-in analyze_month prompt)
• "Record today's rent expense, 25,000"
• "List supplies below their minimum stock"
• "How much delivery revenue did we make last week?"

Available capabilities: read (monthly reports, ledger entries, materials, supplies, suppliers, sales sources, payment methods, expense categories, close status, recurring expenses, daily records) and write (create/update ledger entries, create materials, supplies, suppliers). There are deliberately no delete tools — deletions stay a human job.

Revoking & security

• Click Revoke in the token list — the token stops working immediately.
• A token is a revocable key: within its ceiling, whoever holds it acts as you. Never share it or store it in shared documents.
• Anything the AI completes, plus token creation and revocation, shows up in the audit log.
• Calls refused as web-only, or by the token's own scopes, never touch your data and leave no record — the AI merely asked for something it cannot do. Calls refused for insufficient permission or a closed period do leave a record, showing which token tried what.

Troubleshooting

Symptom	Cause & fix
The AI gets "please log in"	Token mistyped or revoked — create a new one and update your tool's config
"MCP endpoint not found" or 404	Wrong URL (it must end with /api/mcp), or MCP isn't enabled on the server
"Please try again later" (429)	Too many requests — wait a minute
An edit gets rejected	The month is closed, or the entry was created by sync/POS — those protections apply to the AI too