Run QistPay from your AI assistant

Quick start

You need a QistPay account. If you don't have one yet, register your business first.

Claude (claude.ai, Claude Desktop, Claude mobile)

1. Open Settings → Connectors and choose Add custom connector. On Team and Enterprise plans, an owner may need to add it under organization settings first.
2. Name it QistPay and paste the server URL https://qistpay.org/mcp. Leave the OAuth client ID and secret empty; QistPay registers Claude automatically.
3. Click Connect. A QistPay window opens. Sign in, review the requested access and click Allow access.
4. In a new chat, enable the QistPay connector from the tools menu and ask something like "List my QistPay branches."

ChatGPT

1. Open Settings → Apps & Connectors. If you're adding a custom server, turn on developer mode under Advanced settings.
2. Create a connector named QistPay with the URL https://qistpay.org/mcp and authentication set to OAuth.
3. Sign in to QistPay when prompted and click Allow access.
4. Select QistPay in a chat and start asking questions.

Other MCP clients

Any client that supports the Streamable HTTP transport with OAuth 2.1 (Authorization Code + PKCE and Dynamic Client Registration) can connect. Point it at https://qistpay.org/mcp; it discovers everything else from the metadata endpoints listed under Authentication.

Example prompts

Architecture

The assistant never gets direct access to your data. It calls named tools on QistPay's MCP endpoint, and each call is authenticated and checked against your access before anything runs.

• Transport: Streamable HTTP, JSON-RPC 2.0 at POST https://qistpay.org/mcp.
• Business isolation: a connection is tied to your user and your business, and can never reach another business's records.
• Same rules as the web app: an order created from chat updates stock, the installment schedule and the branch ledger exactly as it would in the browser.

Authentication

QistPay uses OAuth 2.1 with Authorization Code + PKCE (S256) and Dynamic Client Registration. AI clients register themselves, so there's no client ID or secret to manage.

1. The client calls /mcp without a token and gets 401 with a WWW-Authenticate header pointing to the protected-resource metadata.
2. It reads the metadata, registers at /oauth/register, and sends you to /oauth/authorize.
3. You sign in to QistPay. The consent screen shows which client is asking, the account you're signed in as, and the requested scopes. Click Allow access or Cancel.
4. The client exchanges the code at /oauth/token for an access token and, if requested, a refresh token.

Scopes

Scopes limit what a connection can do. If a client doesn't ask for specific scopes, it gets the read-only defaults. Write and delete scopes are granted only when the client requests them, and they're listed on the consent screen.

Permissions & branches

Every tool call has to pass two checks:

1. OAuth scope: the connection was granted the tool's scope. Tools outside your scopes aren't even listed to the assistant.
2. QistPay role: your user is currently allowed to do this in QistPay. This is checked on every call, so if an admin changes your role, it takes effect immediately.

Investor-role users only ever see their own investor record. Staff see only what their role allows in the web app.

Explicit branch selection

Branch-scoped tools always need a branch_id. The assistant calls list_branches first and passes the ID explicitly. It never relies on whichever branch you last opened in the browser, so it can't accidentally write to the wrong branch.

Write safety

1. Confirm before every change

Connected assistants are asked to treat every create, update or delete as a conversation:

• Ask for missing details one at a time instead of guessing.
• Search for an existing customer before creating a new one, and ask whether it's the same person.
• Restate the full request (branch, customer, product, prices, plan, dates) in plain language.
• In voice sessions, spell names letter by letter.
• Wait for your explicit "yes" before calling the tool.

2. Preview + one-time token for deletes

Delete tools don't run on request alone. The assistant first calls preview_destructive_action (orders, installments, payments, manual transactions) or preview_business_deletion (customers, products, branches, investor transactions). The preview shows exactly what will be removed or reversed and returns a confirmation_token that:

• expires after 5 minutes and works only once;
• works only for the exact action that was previewed;
• becomes invalid if the record changes after the preview.

3. Idempotency keys

Every write includes an idempotency_key. If the network drops and the assistant retries, QistPay returns the original result instead of recording the payment twice.

4. All-or-nothing changes

A payment updates the installment, the order balance and the branch ledger together, or not at all.

Your responsibility

Good practice:

• Use a staff account with a limited role for day-to-day chat use, and keep admin connections for owners.
• Grant write scopes only if you need them. Read-only is the default.
• Check your activity history after bulk changes.
• Data the assistant reads is sent to your AI provider and handled under its privacy policy.

Activity history

QistPay keeps a record of activity made through MCP connections for security and support. Business changes appear on the Activity Logs page alongside changes made in the browser, and you can review them in chat with list_activity_logs.

Tool reference

Read never changes data. Write creates or changes records and needs an idempotency_key. Delete also needs a confirmation_token from a preview tool.

Account & branches

Customers

Products & inventory

Orders

Installments & payments

Ledger & investors

Invoices, audit & previews

Invoices

Every order has a PDF invoice, the same one as the Invoice button in QistPay. If several invoices match a customer, the assistant asks which one you want. Download links are private and expire after a few minutes.

Errors

When a request can't be completed, the assistant gets a short error code and a readable message so it can explain what went wrong.

If you're signed out of the connection, your assistant will ask you to sign in to QistPay again.

Limits

• Fair use: connections are rate-limited to protect the service. Normal conversational use won't hit the limit.
• Page size: list and search tools return up to 50 results per page; ask the assistant for the next page.
• Currency: all amounts are in Pakistani rupees (PKR).
• Plan limits on your QistPay subscription apply to records created through MCP, just like in the browser.

Disconnecting

To stop an assistant from accessing QistPay, remove the QistPay connector in the assistant's settings (in Claude: Settings → Connectors → QistPay → Disconnect). To revoke all connections immediately, contact support@qistpay.org. Removing a staff user from your business also ends their connections.

FAQ

Does the AI provider get all my data?

No. The assistant only receives the results of the specific tools it calls during your conversation, limited by your scopes and role.

Can a staff member do more through chat than in the app?

No. Every call checks the same role permissions as the web app.

Can the assistant delete something by mistake?

Deletes need a preview and a one-time token, and the assistant is instructed to get your explicit confirmation first. You still need to read what you're approving. See Your responsibility.

Is there a cost?

The MCP connection is included with every QistPay plan. Your AI assistant's own subscription is separate.

Where do I get help?

Email support@qistpay.org or visit qistpay.org/support.