Toolfy works inside ChatGPT Apps. Generate a Personal Access Token (PAT), point ChatGPT at our manifest, and you can create customers, jobs, invoices, and payments directly from a conversation.
At a glance
- Use PATs for secure machine-to-machine authentication.
- Call the ChatGPT-specific OpenAPI manifest to load high-leverage tools.
- Add idempotency keys and attribution headers so retries stay safe and observable.
Prerequisites
Confirm these before you spend time wiring ChatGPT tools.
ChatGPT Apps access
During the pilot this is limited to Toolfy admin emails. Once the add-on launches, only orgs with the ChatGPT Apps add-on enabled will see the AI Assistant tab in settings.
Feature flag
Set AI_ACCESS_ENABLED (and optionally NEXT_PUBLIC_AI_ACCESS_ENABLED) to true in your deployment env so the token UI/API are reachable.
Owner/manager role
Only owners/managers can view Settings → Security and generate PATs. ChatGPT Apps inherit those scopes, so pick the least-privilege role that still unlocks the workflow.
(Optional) ChatGPT App link
Set NEXT_PUBLIC_CHATGPT_APP_URL so Toolfy can show a one-click “Open ChatGPT App” button once your PAT is ready.
1. Access the OpenAPI manifest
Import one of these endpoints in the ChatGPT Apps SDK (or MCP host) to register Toolfy's tools.
Stable (latest)
/api/openapi/chatgptAlways points at the current manifest for the ChatGPT Apps SDK.
Versioned snapshot
/api/openapi/chatgpt/v0Lock to a specific revision for certification or review flows.
2. Authenticate with a PAT
PATs are the fastest way to give ChatGPT Apps scoped access to your Toolfy organisation.
Create a Personal Access Token
Navigate to Settings → Security → Personal Access Tokens, choose the scopes you need, and generate a token.
Store it securely
The PAT is only displayed once. Copy it into your secrets manager before leaving the page.
Send authorised requests
Include the token in the Authorization header on every API call made from ChatGPT Apps.
Required header
Authorization: Bearer <PAT>Optional headers
Idempotency-KeySend a unique key to make retried POST creates safe when de-duplication is enabled (rolling out).x-agentSend "chatgpt" so rate limiting and observability attribute tool usage correctly.Billing suspension handlingEvery write can return 402 BILLING_SUSPENDED if the workspace trial expired or a payment failed. Catch it, explain that Toolfy switched to read-only mode, and link the user to /manage-plan instead of retrying endlessly.
402 BILLING_SUSPENDEDit means the workspace trial expired or billing failed. Surfacing that explanation (and a link tothe billing suspension guide) prevents loops where ChatGPT keeps retrying a write that Toolfy refuses.3. Apply least-privilege scopes
Scopes limit what ChatGPT Apps can do on your behalf. Grant only what the workflow needs.
Read
customers:readjobs:readinvoices:readpayments:readquotes:read
Write
customers:writejobs:writeinvoices:writepayments:writequotes:write
Optional: Install the MCP server
Prefer a tool-based experience? Install the Toolfy MCP server and let ChatGPT invoke tools for you.
Quick install
cd mcp/toolfy-mcp npm i TOOLFY_API_URL=https://app.toolfy.io TOOLFY_PAT=<your_pat> node index.js
The repository README under mcp/toolfy-mcp/ includes environment variables and extended usage notes.
Popular MCP tools
create_or_find_customercreate_jobcreate_quotesend_quoteconvert_quote_to_jobcreate_invoicesend_invoicerecord_paymentsuggest_time_slotsschedule_jobMore resources
Need cURL samples or troubleshooting tips? See docs/CHATGPT_APPS.md in the repository for a detailed walkthrough.
For live assistance, open a ticket via Contact Support or email support@toolfy.io.