MCP API Integration
Connect AI assistants like Claude, ChatGPT, and Cursor to your GetCost account using the Model Context Protocol (MCP). Automate estimates, manage clients, build templates, and run your business with natural language.
What is the MCP API?
OverviewThe Model Context Protocol (MCP) is an open standard that lets AI assistants interact directly with external applications. GetCost's MCP API gives AI tools secure, real-time access to your business data — so you can manage estimates, invoices, clients, products, templates, schedules, timesheets, transactions, and more using natural language.
Supported AI Clients
Any MCP-compatible client can connect to GetCost. Popular options include:
| Client | Type | Configuration |
|---|---|---|
ChatGPT |
Web / Desktop App | Custom connector in developer mode, authenticated with an API key |
Claude Desktop |
Desktop App | Add to claude_desktop_config.json |
Claude Code |
CLI Tool | Add to project .mcp.json or ~/.claude/settings.json |
Cursor |
IDE | Add via MCP settings panel |
Windsurf |
IDE | Add via MCP settings panel |
Custom Client |
Any | Use the Streamable HTTP transport |
Getting Started
SetupConnecting an AI assistant to GetCost takes just two steps: generate an API key, then add the server configuration to your MCP client.
Step 1: Generate an API Key
- Log in to your GetCost account
- Go to Settings → Advanced → MCP API Keys
- Click Create API Key — the new key is copied to your clipboard automatically
- The key starts with
mcp_and stays listed on the screen, so you can copy it again later
An active business is required. You can hold up to 5 API keys per business. Each key provides full access to your account data, so treat them like passwords.
Step 2: Connection Details
Use these details to configure your MCP client:
| Setting | Value |
|---|---|
Server URL |
https://www.getcost.com/mcp |
Transport |
HTTP (JSON-RPC 2.0, single POST per request) |
Protocol version |
2024-11-05 |
Authentication |
Either an API key (static Bearer token) or OAuth 2.1 with PKCE |
Header |
Authorization: Bearer mcp_your_key_here |
Capabilities |
tools, resources, prompts |
Two ways to authenticate
Both are fully supported — pick whichever your client offers:
| Method | How it works | Best for |
|---|---|---|
| API key | Create a key in Settings | Advanced | MCP API Keys and send it as
Authorization: Bearer mcp_… |
Claude Code, scripts, .mcp.json, curl |
| OAuth 2.1 | The client discovers the authorization server, registers itself, and the user signs in and approves in the browser. No key is ever copied by hand. | ChatGPT and any client that expects a sign-in |
OAuth endpoints
A client normally finds all of these on its own. It starts by calling the MCP endpoint with
no token, gets a 401 whose WWW-Authenticate header points at the
protected resource metadata, and follows the chain from there.
| Endpoint | Purpose |
|---|---|
/mcp/.well-known/oauth-protected-resource | Names the resource and its authorization server (RFC 9728) |
/.well-known/oauth-authorization-server | Authorization server metadata (RFC 8414) |
/oauth/register | Dynamic client registration (RFC 7591) |
/oauth/authorize | Sign in and approve; returns an authorization code |
/oauth/token | Exchange the code for tokens, and refresh them |
Public clients only: no client secret is issued, PKCE with S256 is required, and redirect URIs must match exactly what was registered. Access tokens last one hour; refresh tokens rotate on every use.
Connecting Your AI Client
Configuration
Below are configuration examples for the most popular MCP clients. Replace
mcp_your_key_here with your actual API key from Step 1.
ChatGPT
ChatGPT connects to GetCost as a plugin (custom connector), added from Settings | Plugins. It is available on Plus, Pro, Business, and Enterprise plans and requires developer mode. On Business and Enterprise workspaces, an admin must allow it first.
- Open Settings → Plugins and click Developer mode — it opens Settings | Security and login, where you switch it on.
- Back in Settings → Plugins, click Browse Plugins, then + to add a new one.
-
Set Name to
GetCostand MCP server URL tohttps://www.getcost.com/mcp. -
Choose the Authentication that ChatGPT offers you:
- OAuth — nothing to paste. ChatGPT opens GetCost, you sign in and approve, and it is connected.
- API key (also shown as access token) — paste your
mcp_key; it is sent asAuthorization: Bearer mcp_….
- Confirm you trust the connector, then click Create.
- In a new conversation, enable GetCost from the + / tools menu, then try "List my clients".
search and fetch tools. GetCost exposes a full read/write
tool set instead, so it is intended for developer-mode chat, not deep research.
Claude Desktop
Edit your Claude Desktop configuration file. On macOS it is located at
~/Library/Application Support/Claude/claude_desktop_config.json,
on Windows at %APPDATA%\Claude\claude_desktop_config.json.
claude_desktop_config.json
{
"mcpServers": {
"getcost": {
"type": "http",
"url": "https://www.getcost.com/mcp",
"headers": {
"Authorization": "Bearer mcp_your_key_here"
}
}
}
}
Claude Code (CLI)
Create a .mcp.json file in your project root, or add to your
global settings at ~/.claude/settings.json.
.mcp.json
{
"mcpServers": {
"getcost": {
"type": "http",
"url": "https://www.getcost.com/mcp",
"headers": {
"Authorization": "Bearer mcp_your_key_here"
}
}
}
}
Cursor / Windsurf
Open the MCP settings in your IDE and add a new HTTP server with the URL
https://www.getcost.com/mcp and the authorization header.
Refer to your IDE's documentation for the exact location of MCP settings.
Custom or Programmatic Client
If you are building your own MCP client, POST JSON-RPC 2.0 requests to the endpoint with a
Bearer token in the Authorization header. The server reports protocol version
2024-11-05 and replies with a plain application/json body (no SSE
stream). Notifications such as notifications/initialized are answered with
HTTP 202 and no body.
Example: Raw HTTP Request
POST https://www.getcost.com/mcp HTTP/1.1
Content-Type: application/json
Authorization: Bearer mcp_your_key_here
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/list",
"params": {}
}
What Can You Do?
CapabilitiesThe GetCost MCP API exposes over 110 tools across every major area of the platform. Here are some of the things your AI assistant can do:
Estimates & Invoices
Create, edit, and share documents with full control over line items and pricing.
- Create new estimates and invoices
- Add, remove, and update line items with pricing
- Set document names, descriptions, and client associations
- Generate shareable links for client review
- Search and query existing documents
Templates & Scripting
Build and manage interactive estimation templates with full scripting support.
- Create templates with form elements (text fields, checkboxes, dropdowns, numeric inputs)
- Write and edit JavaScript automation scripts on template elements
- Run scripts to test calculations and logic
- View template version history and compare changes
- Search across all template scripts with regex patterns
Clients
Manage your customer database directly through conversation.
- Create new clients with name, phone, address, and email
- Search clients across all fields (name, phone, address)
- Update client information
- Associate clients with documents and schedules
Product Catalog
Manage your products and services inventory.
- Search the global product catalog
- Create, update, and delete products with pricing
- Assign products to categories and attribute groups
- Browse the product category hierarchy
Scheduling & Time Tracking
Manage your calendar and track billable hours.
- Create and manage schedule events
- Log timesheet entries with duration, rate, and comments
- Associate time entries with clients and projects
Financial Tracking
Record expenses, income, and manage bank accounts.
- Create expense and income transactions
- Categorize transactions and assign to bank accounts
- Search and filter transactions by date, amount, client, or status
- Batch update transactions (e.g., validate all transactions in a date range)
- Generate financial reports with date filtering
- Manage bank accounts with opening balances
Navigation & Context
The AI assistant is aware of what you are viewing on screen.
- Read your current screen context (which document, client, or page you have open)
- Navigate you to any page, document, or template in the application
- View application console logs for debugging
Tool Reference
ReferenceThe table below lists all available MCP tools grouped by category. Each tool is called automatically by your AI assistant based on your request — you do not need to call them directly.
Document & Template Management
| Tool | Description |
|---|---|
document_create | Create a new estimate or invoice |
document_convert | Convert an estimate into an invoice |
estimate_make | Build a complete estimate in one call |
invoice_make | Build a complete invoice in one call |
document_get | Get document properties (name, type, client) |
document_set | Update document properties |
document_delete | Delete a document |
document_share | Generate a shareable link for a document |
template_create | Create a new design template |
template_get | Get template properties and metadata |
template_set | Update template name, description, access rights, industries |
template_delete | Delete a template |
template_history_list | List saved versions of a template |
template_history_get | Retrieve a specific version from history |
template_history_diff | Compare two template versions |
templates_grep_script | Search regex patterns across all template scripts |
Elements & Scripting
| Tool | Description |
|---|---|
document_get_element | Get elements from a document or template |
document_add_element | Add a new element (item, text, numeric, checkbox, section) |
document_remove_element | Remove an element |
element_get | Get element properties |
element_set | Update element properties (name, value, price, quantity) |
element_move | Move an element to a new position |
element_set_script | Set a JavaScript automation script on an element |
element_get_script | Read the script from an element |
element_edit_script | Edit a script using find/replace |
element_grep_script | Search within a script using regex |
element_edit | Edit element properties using find/replace |
element_run_script | Execute the script on an element |
run_script | Execute standalone JavaScript in the GetCost sandbox |
Template Files
The JavaScript files a template's script imports (lib/pricing.js ...) - see
Template API, Template Files. They work on a template, or on a
template's form inside a document (elementId); a write takes effect at once and saves a
new version.
| Tool | Description |
|---|---|
template_file_list | List a form's files and the version each runs |
template_file_get | Read a file (a line range, or an older version) |
template_file_set | Create or overwrite a file |
template_file_edit | Edit a file using find/replace (exactly one match) |
template_file_grep | Search a form's files using regex |
templates_grep_files | Search the files of all your team's templates using regex |
template_file_history | List the saved versions of a file |
template_file_diff | Compare two versions of a file |
Products & Catalog
| Tool | Description |
|---|---|
items_search | Search the global product catalog |
item_create | Create a new product |
item_get | Get product details |
item_set | Update a product |
item_delete | Delete a product |
item_category_get | Get category details and path |
item_category_search | Browse and search the category hierarchy |
industry_search | Search for industries to link to templates |
Clients, Scheduling & Time
| Tool | Description |
|---|---|
client_create | Create a new client |
client_get | Get client details |
client_set | Update client information |
client_merge | Merge a duplicate client into another client |
client_search | Search clients by name, phone, address |
lead_create | Create a lead |
lead_get | Get lead details |
lead_set | Update a lead |
lead_search | Search leads |
contract_create | Create a contract |
contract_get | Get contract details |
contract_set | Update a contract |
contract_delete | Delete a contract |
contract_search | Search contracts |
schedule_create | Create a schedule event |
schedule_available_slots | Find free slots in the schedule |
schedule_get | Get schedule event details |
schedule_set | Update a schedule event |
schedule_delete | Delete a schedule event |
timesheet_create | Log a timesheet entry |
timesheet_get | Get timesheet entry details |
timesheet_set | Update a timesheet entry |
timesheet_delete | Delete a timesheet entry |
mileage_create | Log a mileage entry |
mileage_get | Get a mileage entry |
mileage_set | Update a mileage entry |
mileage_delete | Delete a mileage entry |
mileage_search | Search mileage entries |
travel_search | Search recorded travel history |
travel_last_location | Get the last known location of a device |
travel_devices | List devices reporting travel data |
travel_set | Update travel tracking settings |
agenda_create | Create an agenda entry |
agenda_get | Get an agenda entry |
agenda_set | Update an agenda entry |
agenda_delete | Delete an agenda entry |
agenda_search | Search agenda entries |
Email & Chat
| Tool | Description |
|---|---|
email_accounts | List the connected email accounts |
email_folders | List folders in a mailbox |
email_folder_create | Create a mailbox folder |
email_folder_rename | Rename a mailbox folder |
email_folder_delete | Delete a mailbox folder |
email_refresh | Sync the mailbox with the mail server |
email_search | Search messages |
email_grep | Search inside message bodies with regex |
email_get | Read a message, with the list of its attachments |
email_get_attachment | Get a file attached to a message (fetched from the mail server the first time); its content is read through getcost://upload/{uploadId} |
email_set | Update message flags (read, starred, folder) |
email_batch | Apply an update to many messages at once |
email_move | Move a message to another folder |
email_create | Create a draft message |
email_edit | Edit a draft using find/replace |
email_add_attachment | Attach a file to a draft: one already in GetCost (uploadId) or the file given in a ChatGPT conversation |
email_remove_attachment | Remove a file from a draft (the file itself is kept) |
email_send | Send a message |
channel_search | Search chat channels |
channel_create | Create a chat channel |
chat_search | Search chat messages (drafts, unread) |
chat_get | Read messages from a channel or user, with each message's files (read one through getcost://upload/{uploadId}) |
chat_send | Prepare a chat message for the user to send |
chat_add_attachment | Attach a file to the chat message being written: one already in GetCost (uploadId) or the file given in a ChatGPT conversation. Not sent: the user sends it from the chat |
chat_remove_attachment | Remove a file from the chat message being written |
note_search | List private notes, your own or a client's |
note_create | Write a private note (markdown, saved immediately) |
note_set | Change a note's text or colours |
note_delete | Delete a note |
Settings, Team & Files
| Tool | Description |
|---|---|
settings_user_get | Read the current user's settings |
settings_profile_get | Read a permission profile |
settings_business_get | Read a business setting |
settings_business_list | List the businesses you belong to |
settings_business_select | Switch your active business to another one you belong to |
settings_screen_get | Read screen visibility settings (omit screen for all) |
settings_screen_set | Change screen visibility settings |
team_members | List the members of the business |
upload_search | Search uploaded files and photos by document, type, file name, date, or what was said in a video or recording |
upload_create | Attach a new photo or PDF to an estimate or invoice (in ChatGPT, a file attached in the conversation) |
upload_delete | Delete a document photo or a Gallery photo (to keep it, use document_remove_upload) |
document_add_upload | Attach a file you already have (Gallery, another document, chat, email) to an estimate or invoice - shared, not copied |
document_remove_upload | Take a photo off an estimate or invoice - it moves to the Gallery, nothing is deleted |
document_set_upload | Change the caption of a photo on an estimate or invoice |
newsletter_subscribe | Subscribe an email address to the newsletter |
Financial & Reporting
| Tool | Description |
|---|---|
transaction_create | Record an expense or income |
transaction_get | Get transaction details |
transaction_set | Update a transaction (amount, category, tax) |
transaction_delete | Delete a transaction |
transaction_search | Search and filter transactions |
transaction_batch | Batch update transactions matching a filter |
transaction_category_list | List expense/income categories |
account_create | Create a bank account |
account_get | Get bank account details |
account_set | Update a bank account |
account_search | Search bank accounts |
report_get | Generate financial reports (expenses, income, balance) |
Navigation & Utilities
| Tool | Description |
|---|---|
navigate | Navigate the user to any page in GetCost, or open a chat dialog via chat?openUserId={id}. GetCost must be open: if it is not, nothing is shown and the tool says so (with when you were last seen). If it is open in the background, the page still changes and the tool notes you will see it when you come back. |
get_logs_tail | View recent console log entries |
get_logs_filter | Filter console logs by level or text |
Example Conversations
ExamplesOnce connected, you interact with GetCost using natural language. Your AI assistant translates your requests into the appropriate MCP tool calls automatically. Here are some things you can say:
Creating an Estimate
You: Create a new estimate for Sarah Johnson. Add drywall repair
for $450 and interior painting for $1,200.
AI: I've created a new estimate and associated it with Sarah Johnson.
I added two line items:
- Drywall Repair: $450.00
- Interior Painting: $1,200.00
Total: $1,650.00
Building a Template
You: Create a bathroom renovation template with fields for
room dimensions and a checkbox for tub-to-shower conversion.
AI: I've created a "Bathroom Renovation" template with:
- Length (numeric, feet)
- Width (numeric, feet)
- Tub-to-Shower Conversion (checkbox)
I also added a script that calculates tile area based
on the dimensions.
Managing Clients
You: Find all clients in Austin, Texas.
AI: I found 3 clients in Austin:
1. Mike Reynolds - 512-555-0147
2. Lisa Chen - 512-555-0283
3. David Park - 512-555-0391
Tracking Finances
You: Log a $350 expense for lumber at Home Depot,
categorize it as Materials, and assign it to my
Business Checking account.
AI: I've recorded the expense:
- Name: Lumber - Home Depot
- Amount: $350.00
- Category: Materials
- Account: Business Checking
Running Reports
You: Show me a summary of my expenses and income
for January 2025.
AI: Here's your January 2025 financial summary:
- Total Expenses: $4,230.00
- Total Income: $12,750.00
- Net: +$8,520.00
Sharing Documents
You: Share the kitchen renovation estimate with the client.
AI: I've generated a shareable link for the estimate.
The client can view and review it online.
Resources & Context
AdvancedIn addition to tools, the MCP server exposes resources that provide real-time context about your current session, and a prompt that teaches the assistant the GetCost scripting SDK:
getcost://context
Returns your current screen context, including the document or template you have open, the associated client, your user ID, and business ID. AI assistants read this automatically so they know what you are working on without being told.
It also tells the assistant which business is active and whether you are in GetCost right now:
activeBusiness- the business you are working in right now ({ id, name }), andbusinessCount- how many businesses you belong to. When you have more than one,settings_business_listlists them all.available- GetCost is open somewhere (a browser tab or the mobile app).present- GetCost is in front of you. A tab in the background or a locked phone counts as open but not present.awaySince/awayFor- when you were last looking at GetCost, and how long ago (for example "3 hours"). Empty while you are present, or when it is not known.
getcost://upload/{id}
Retrieves an uploaded file by ID. Images are resized and returned as base64 JPEG, PDFs are
converted to markdown text, and text files are returned as-is. Supports the query parameters
maxWidth, maxHeight (default 1568), quality
(default 85) and format (base64, markdown, text).
scripting_guide (prompt)
Returns the GetCost JavaScript V3 SDK documentation so the assistant can write template
scripts correctly. Takes an optional topic argument:
quickstart, v3-sdk, api-reference,
examples, or all.
Troubleshooting
HelpCommon Issues
| Problem | Solution |
|---|---|
| Connection refused or timeout | Verify the server URL is https://www.getcost.com/mcp and your network allows HTTPS traffic |
JSON-RPC error -32001, "Authentication failed" |
Check that your API key is correct and includes the Bearer prefix in the header |
| The client's OAuth sign-in never completes | Check that the whole flow is reachable: the 401 on /mcp must carry a
WWW-Authenticate header, and /oauth/authorize must open the
GetCost sign-in page. If OAuth has been disabled server-side these answer 404, and
the client should be configured with an API key instead. |
| ChatGPT creates the connector but no tools run | Confirm developer mode is on, the authentication type is API key (not "No authentication"), and that GetCost is enabled from the + menu of that conversation. |
| "MCP is temporarily disabled" | The MCP endpoint has been turned off server-side for maintenance. Try again later. |
| "This feature requires an active subscription" | That tool needs a paid plan. The rest of the tools keep working. |
navigate says "the GetCost app is not open for this user right now" |
The assistant can only show you a page while GetCost is open. Open GetCost in your browser or the mobile app, then ask again. |
| Tools not showing | Restart your AI client after adding the MCP configuration. Some clients require a restart to detect new servers. |
| API key not working | Generate a new key from Settings → MCP API Keys. Old keys may have been deleted. |
| "No business" error | Ensure your GetCost account has an active business profile set up |
https://www.getcost.com/mcp with the
tools/list method. A successful response confirms your API key and connection are working.