Operational connector guide

RetailHardHat exposes a remote MCP server at `/api/mcp`, using stateless Streamable HTTP with JSON responses. It supports tools, resources, prompts, and MCP protocol initialization through the official TypeScript SDK.

Start with Developer documentation, also served publicly at /api/mcp-public/docs, for the full reference, runnable client and extension guide.

Connect an AI provider using OAuth

Use https://app.retailhardhat.com/api/mcp as the remote Streamable HTTP URL after publishing this version. Supported clients discover the OAuth server, register a client, and open the RetailHardHat consent page. Sign in through the Admin portal as an organization owner/admin, verify the client and callback origin, then select the modules and read-only or guarded-write access.

OAuth uses PKCE S256, one-hour access tokens, rotating refresh tokens, and a maximum 90-day grant. Refresh can narrow permissions, never expand them. Reusing a consumed refresh token revokes the grant. Required in-app review binds immutable arguments; configurable rules may waive extra MCP review, never underlying business approval. Revoke access in Settings → MCP → Connections.

See provider setup and submission for discovery addresses, package generation, tests, and the external publisher/review steps. The Providers tab distinguishes local configuration from directory acceptance. A real Microsoft token-store registration is required to finish the Copilot sideload ZIP; templates are not a substitute.

Connect a legacy bearer-header client

1. Sign in as an organization owner or administrator.
2. Open Settings → MCP → New connection.
3. Choose the modules, read-only or guarded-write access, and expiry (1–90 days).
4. Copy the token when it is displayed. It is shown once and cannot be recovered.
5. Open Setup and copy the configuration for Cursor, VS Code, or Claude Code.

Use the URL of the environment you intend to connect to.

Example for clients using mcpServers:

{
  "mcpServers": {
    "retailhardhat": {
      "url": "https://YOUR_APP_HOST/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_TOKEN"
      }
    }
  }
}

VS Code uses a servers object rather than mcpServers, with "type": "http". Claude Code accepts:

claude mcp add --transport http retailhardhat https://YOUR_APP_HOST/api/mcp --header "Authorization: Bearer YOUR_MCP_TOKEN"

Treat a connection token as a password. Store it in your AI client's supported secret mechanism where available. Never put a real token in a repository, shared configuration, prompt, screenshot, or support message.

The manual-token flow remains supported alongside browser OAuth. No legacy SSE subscription or outbound MCP-client functionality is provided.

Supported modules

Sites, deals, tasks, projects, whole budgets and budget categories, vendors, permits, bids, RFIs, RFPs, contacts, construction invoices, change requests and their financial line items, purchase lists/templates/tracking, documents and folders, synchronized leases, field operations, and organization reports. Field operations include daily logs/photos, punch lists, utilities and closeout document records. The Tools tab is the live catalogue. The MCP tools/list response only includes the modules and write access granted to that connection. Entity operations use the existing application's API validation, business rules, and tenant restrictions. Identity, credential, platform-admin, direct payment and arbitrary SQL/HTTP operations are deliberately not exposed.

Paged list tools support limit (1–100), offset, optional text search, and applicable site/status/project filters. Array responses become { items, total, limit, offset, nextOffset }; endpoint-specific summaries retain their application response shape. Use nextOffset to retrieve the next page. Monetary values are decimal strings without currency symbols; date fields accept ISO calendar dates or date-time strings according to the tool schema.

Existing connections retain their original scopes. Create a new connection with the additional modules selected to make these tools available; publishing does not silently expand an existing token's permissions.

File workflow

1. Call request_file_upload with the MIME type and exact byte length (maximum

50 MiB). Both policies must allow document sharing. If current rules require review, approve and execute the request.

1. PUT the bytes directly to the returned uploadURL, with the matching

Content-Type. This signed URL expires in 15 minutes; keep it private.

1. Pass the returned key to the appropriate attach_*_document tool (or

attach_daily_log_photo). Each write follows its current approval rule. An unclaimed upload must originate from the same MCP connection and be attached within one hour. Existing organization-owned files may be reused.

1. Use read_*_document to retrieve text or base64 file bytes, up to 2 MiB.

Larger files should be downloaded in the app. Invoice attachments also have an existing short-lived get_invoice_download_url tool.

File paths are managed App Storage keys, not arbitrary URLs. A tool cannot claim another organization's files, change storage identity through a metadata edit, or attach an unknown/unclaimed key. Upload URLs and file bytes are not persisted in MCP activity. Document and folder deletion follows the existing app's rules, including its cascading behavior; do not assume every module physically removes the underlying file.

Financial and lease boundaries

Budget edits/deletions do not offer force, approval or lock overrides. Invoice tools create/edit business records but do not move money or mark invoices paid. Change-request tools do not self-approve requests or set financial-impact-applied flags. These workflows still run through the app's ordinary business controls. LeaseCommand remains authoritative for lease contents: MCP reads cached leases and activity, checks connection status, and can request an approved refresh using an already-configured integration. It does not create source leases or manage integration credentials.

Resources: retailhardhat://connection and retailhardhat://tools. Prompts: operations_review and budget_review.

Approval lifecycle

• Ordinary task creation/editing runs immediately by default for guarded-write connections.
• Sensitive writes require approval by default. Organization/connection rules may

require or waive extra MCP review by tool, action or sensitivity family. Existing business approvals remain enforced.

• Writes requiring review return `pending_approval`.

No requested business change has happened yet.

• A human opens Settings → MCP → Approvals, checks the exact tool and

arguments, and explicitly approves or rejects. Approval does not execute.

• The same AI connection polls get_approval_status, then calls

execute_approved_action with the approval ID.

• Arguments come from the stored request, not from the execution call.

Approvals expire after the configured interval (default/maximum 24 hours), are connection/tenant-bound, and can be consumed once. Concurrent execution attempts cannot use the same approval.

• Rejected, expired, used, and revoked-connection approvals cannot execute.
• Policy updates invalidate pending and approved requests.
• If execution fails or the outcome is uncertain, inspect application records

before requesting a new approval. Never automatically retry mutations. An executing request left after a process interruption is intentionally not reusable; check its activity and underlying records.

• Deletions may cascade under the app's normal rules. Review them carefully.

Administration and security

Connections act as the administrator who created them, never as a platform superadmin. The creator's current role and suspension state are checked on every MCP request. Removing their account or administrator role disables access. Switching the creator's browser organization does not change a token's tenant.

Only SHA-256 hashes of high-entropy tokens are stored. Tokens have expiry and can be revoked immediately. MCP never accepts a browser cookie instead of a bearer token. Session-based management endpoints still require CSRF protection. Existing CORS restrictions remain in place.

Actual operations run with short-lived, server-side delegated sessions through the existing API, on the local server only. These session credentials are never returned to clients. Foreign-key organization checks add protection for legacy routes. Secret-like response fields are removed recursively.

Requests are subject to the app's global rate limiter and persistent organization/user/connection limits. Default connection budgets are 120 requests/minute, four concurrent client operations, 100 changes/hour and 50 MiB download accounting/hour. Organization policy imposes ceilings. Response caps default to 2 MiB; API execution has a 25-second timeout. Narrow an oversized query rather than assuming it returned complete results.

Settings → MCP → Security manages module/action/tool/record restrictions, approval rules, document/export grants, field masks, quotas, approved actual OAuth registration IDs, security activity and in-app alerts. Unsupported record scopes fail closed. Connection document/export grants default off. Masks redact JSON fields, not attachment contents. Emergency shutdown permanently revokes old credentials; re-enabling does not restore them. See Security reference.

Connections, approvals and activity are persistent PostgreSQL records installed by the app's normal SQL migrations. The Settings view shows all active connections and unexpired open requests, plus the latest 200 connections/requests and 100 activity entries. Older activity remains in the database. No secrets or business payload results are stored in activity rows. Exact action arguments are stored only on approval requests for human review.

Verification

See Testing and release checks for protocol, OAuth, security, native-view, documentation-client and browser suites.

Only explicit development startup applies SQL migrations. Production and publish-test startup perform read-only checks; Publish owns production schema changes. After publishing, create a separate connection in the live organization; do not reuse development tokens against production.

Download this guide as Markdown.