Skip to main content
SnapCount logoSnapCount
Browse Developers: MCP server

Remote MCP server

Connect an AI assistant to SnapCount with one address and OAuth browser approval. It reads counts and reports and can create counters and live links. It cannot change a count.

Updated

On this page
  1. Endpoint and transport
  2. Plans
  3. OAuth and discovery
  4. Scopes
  5. Tools
  6. Prompts
  7. Errors
  8. Limits and records
  9. Disconnect an assistant
  10. Test with MCP Inspector

Endpoint and transport

SnapCount runs one remote MCP server for AI assistants. Paste this address into any assistant that can add a remote MCP server with OAuth:

Server address
https://api.snapcount.app/mcp
  • Transport: Streamable HTTP, stateless. Requests are POST with JSON responses. GET and DELETE answer 405.
  • The assistant acts as the signed-in user who approved it, with the same roles, organizations and per-counter access as in the app.
  • There is no public write API. The MCP server cannot change, reset, undo or set a count, delete or archive counters, remove members, change roles, or touch billing.

Step-by-step setup for Claude, ChatGPT, Cursor, VS Code, Codex, Antigravity, Lovable, Replit, Warp, Zed, OpenCode, Hermes and Grok is on the AI assistants page.

Plans

The connection is part of Pro and Enterprise, including the Event Pass and lifetime plans. It is not in the trial or the free plan.

  • Any signed-in user can open the consent screen. Approving needs at least one organization on Pro and Enterprise. Otherwise the decision answers 403 with PLAN_REQUIRED and the request stays open, so the user can upgrade and approve it.
  • Every tool refuses an organization that is not on Pro and Enterprise: the result has isError: true, the code PLAN_REQUIRED, and an upgrade_url to https://snapcount.app/pricing. list_organizations marks each organization with assistant_access.
  • Within those plans each tool keeps the rule of the app screen it mirrors: busiest times, by person and timestamped events need Enterprise, and starting a live link needs an owner or admin.

OAuth and discovery

OAuth 2.1 with browser approval. There is no API key. Clients register themselves with dynamic client registration (RFC 7591) or identify with a Client ID Metadata Document. PKCE with S256 is required.

Discovery and OAuth endpoints
WhatURL
Protected resource metadata (RFC 9728)https://api.snapcount.app/.well-known/oauth-protected-resource/mcp
Authorization server metadata (RFC 8414)https://api.snapcount.app/.well-known/oauth-authorization-server
Authorizehttps://api.snapcount.app/oauth/authorize
Tokenhttps://api.snapcount.app/oauth/token
Client registrationhttps://api.snapcount.app/oauth/register
Revokehttps://api.snapcount.app/oauth/revoke
Read the resource metadata
curl https://api.snapcount.app/.well-known/oauth-protected-resource/mcp

Approval and tokens

  • The authorize step sends the user to a consent screen on https://snapcount.app/oauth/authorize. It names the client and the host its redirect points at, and lists what will be granted.
  • Access tokens last 1 hour. Refresh tokens last 30 days and rotate on every use.
  • Tokens are stored hashed. A refresh token used twice revokes the whole connection.

Scopes

Scopes
ScopeConsent screen text
counters:readSee your organizations, counters, live totals, reports and live links
counters:writeCreate counters and start live counting links

A client that asks for no scope gets both. The consent screen always lists what is granted.

Tools

Six tools. The names are stable. They answer for organizations on Pro and Enterprise, and each keeps the plan and role rule of the screen it mirrors in the app.

Tools
ToolScopeAnnotationsWhat it doesPlan and role
list_organizationscounters:readRead-onlyYour organizations, your role in each, the plan, and how many counters and groups each one has.Any member. It says which organizations are on Pro or Enterprise, the only ones the other tools answer for.
list_counterscounters:readRead-onlyEvery counter you can see with its live count, goal and lock, grouped by store or worker, with each group's total.Any member of a Pro or Enterprise organization.
get_reportcounters:readRead-onlyA snapshot, the daily report (high, low, end of day, events, top counter per day), busiest times, counts by person, or each count with its time, for up to 90 days, in your time zone.Snapshot and daily: Pro or Enterprise. Busiest times, by person and timestamped events: Enterprise.
list_live_linkscounters:readRead-onlyThe live counting links that are running, their counters, the link, and how many devices are connected.Pro or Enterprise.
create_counterscounters:writeWrites, not destructive, not idempotentOne new group with up to 50 named counters, one per store, door or worker, added up by default.Needs write access, on Pro or Enterprise.
start_live_linkcounters:writeWrites, not destructive, idempotentStarts a live link for up to 30 counters, or hands back the one already running: a link and a QR code anyone can count on without an account.An owner or admin, on Pro or Enterprise.

Live links have the shape https://snapcount.app/guest/SESSION_ID. Anyone with the link or its QR code can count on it without an account.

Prompts

Assistants that list prompts show these. A prompt gives the assistant the steps; the tools above still apply their own rules.

Prompts
PromptOptional argumentsWhat it does
daily_reportorganization, dateEach store's or worker's count for the day, next to the same weekday a week earlier, with any unit that has no counts flagged. Ready to send up the chain.
weekly_revieworganization, weeksTotals per unit per week, the best and worst units, and the trend.
set_up_countingwhat, unitsProposes counters, creates them once you agree, then starts a live link and hands back the link for the team.

Errors

A tool that cannot do what was asked returns a result with isError: true and a message the assistant can act on: which plan or role is needed, which organization name did not match, or which limit was reached. The assistant reads it and tells the user what to do. An organization that is not on Pro and Enterprise gets PLAN_REQUIRED.

HTTP responses
StatusWhen
401No valid access token: never approved, expired, or disconnected. The assistant signs in again.
403On the consent decision only: PLAN_REQUIRED, the user has no organization on Pro and Enterprise.
405A GET or DELETE on the MCP address.
429Over 300 tool calls in an hour. Wait for the number of seconds in Retry-After.

Limits and records

  • 300 tool calls an hour per user, across every assistant they connect.
  • Reports cover a date range of up to 90 days, in the user's time zone.
  • create_counters makes one group with up to 50 counters. start_live_link takes up to 30 counters.
  • Every tool call is recorded for 90 days: the tool, whether it worked, the client, the organization, and how long it took.

Disconnect an assistant

Signed-in users see each connected assistant and its recent activity in Settings, Developers, AI assistants, and can disconnect any one. The next call from that assistant fails with 401. Clients can also revoke their own tokens at https://api.snapcount.app/oauth/revoke.

Test with MCP Inspector

Try the server before wiring it into an assistant with the MCP Inspector:

Terminal
npx @modelcontextprotocol/inspector
  1. Set the transport to Streamable HTTP and the URL to https://api.snapcount.app/mcp.
  2. Connect. The Inspector runs the OAuth flow, and your browser opens the SnapCount consent screen.
  3. List the tools and prompts, then call list_organizations to see what your account can reach.
Calls from the Inspector count toward the same hourly limit and are recorded like any other assistant's calls.

Was this page helpful?

Connect SnapCount to your stack

Create an API key or a webhook endpoint in Settings. The public API and webhooks come with Pro and Enterprise.

Open developer settingsCompare plans