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?

Overview

The 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.

Why use MCP? Instead of manually navigating screens, you can tell your AI assistant things like "Create an estimate for John Smith's kitchen renovation" or "Show me all unpaid invoices from last month" and it will interact with GetCost on your behalf.

Supported AI Clients

Any MCP-compatible client can connect to GetCost. Popular options include:

ClientTypeConfiguration
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

Setup

Connecting 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

  1. Log in to your GetCost account
  2. Go to Settings → Advanced → MCP API Keys
  3. Click Create API Key — the new key is copied to your clipboard automatically
  4. 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.

Security: Keep your API key private. Never share it publicly or commit it to version control. You can delete compromised keys at any time from the settings page.

Step 2: Connection Details

Use these details to configure your MCP client:

SettingValue
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:

MethodHow it worksBest 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.

EndpointPurpose
/mcp/.well-known/oauth-protected-resourceNames the resource and its authorization server (RFC 9728)
/.well-known/oauth-authorization-serverAuthorization server metadata (RFC 8414)
/oauth/registerDynamic client registration (RFC 7591)
/oauth/authorizeSign in and approve; returns an authorization code
/oauth/tokenExchange 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.

Users stay in control: every application connected with OAuth is listed under Settings | Advanced | MCP API Keys, where it can be disconnected. Disconnecting revokes its tokens immediately.

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.

  1. Open Settings → Plugins and click Developer mode — it opens Settings | Security and login, where you switch it on.
  2. Back in Settings → Plugins, click Browse Plugins, then + to add a new one.
  3. Set Name to GetCost and MCP server URL to https://www.getcost.com/mcp.
  4. 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 as Authorization: Bearer mcp_….
    Do not choose No authentication — every tool call would be rejected.
  5. Confirm you trust the connector, then click Create.
  6. In a new conversation, enable GetCost from the + / tools menu, then try "List my clients".
Deep research: ChatGPT's deep research mode expects a connector exposing the specific 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": {}
}
Verify your connection: After configuring your client, try asking "List my recent estimates" or "Search for a client named Smith". If the AI can retrieve your data, the connection is working.

What Can You Do?

Capabilities

The 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

Reference

The 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

ToolDescription
document_createCreate a new estimate or invoice
document_convertConvert an estimate into an invoice
estimate_makeBuild a complete estimate in one call
invoice_makeBuild a complete invoice in one call
document_getGet document properties (name, type, client)
document_setUpdate document properties
document_deleteDelete a document
document_shareGenerate a shareable link for a document
template_createCreate a new design template
template_getGet template properties and metadata
template_setUpdate template name, description, access rights, industries
template_deleteDelete a template
template_history_listList saved versions of a template
template_history_getRetrieve a specific version from history
template_history_diffCompare two template versions
templates_grep_scriptSearch regex patterns across all template scripts

Elements & Scripting

ToolDescription
document_get_elementGet elements from a document or template
document_add_elementAdd a new element (item, text, numeric, checkbox, section)
document_remove_elementRemove an element
element_getGet element properties
element_setUpdate element properties (name, value, price, quantity)
element_moveMove an element to a new position
element_set_scriptSet a JavaScript automation script on an element
element_get_scriptRead the script from an element
element_edit_scriptEdit a script using find/replace
element_grep_scriptSearch within a script using regex
element_editEdit element properties using find/replace
element_run_scriptExecute the script on an element
run_scriptExecute 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.

ToolDescription
template_file_listList a form's files and the version each runs
template_file_getRead a file (a line range, or an older version)
template_file_setCreate or overwrite a file
template_file_editEdit a file using find/replace (exactly one match)
template_file_grepSearch a form's files using regex
templates_grep_filesSearch the files of all your team's templates using regex
template_file_historyList the saved versions of a file
template_file_diffCompare two versions of a file

Products & Catalog

ToolDescription
items_searchSearch the global product catalog
item_createCreate a new product
item_getGet product details
item_setUpdate a product
item_deleteDelete a product
item_category_getGet category details and path
item_category_searchBrowse and search the category hierarchy
industry_searchSearch for industries to link to templates

Clients, Scheduling & Time

ToolDescription
client_createCreate a new client
client_getGet client details
client_setUpdate client information
client_mergeMerge a duplicate client into another client
client_searchSearch clients by name, phone, address
lead_createCreate a lead
lead_getGet lead details
lead_setUpdate a lead
lead_searchSearch leads
contract_createCreate a contract
contract_getGet contract details
contract_setUpdate a contract
contract_deleteDelete a contract
contract_searchSearch contracts
schedule_createCreate a schedule event
schedule_available_slotsFind free slots in the schedule
schedule_getGet schedule event details
schedule_setUpdate a schedule event
schedule_deleteDelete a schedule event
timesheet_createLog a timesheet entry
timesheet_getGet timesheet entry details
timesheet_setUpdate a timesheet entry
timesheet_deleteDelete a timesheet entry
mileage_createLog a mileage entry
mileage_getGet a mileage entry
mileage_setUpdate a mileage entry
mileage_deleteDelete a mileage entry
mileage_searchSearch mileage entries
travel_searchSearch recorded travel history
travel_last_locationGet the last known location of a device
travel_devicesList devices reporting travel data
travel_setUpdate travel tracking settings
agenda_createCreate an agenda entry
agenda_getGet an agenda entry
agenda_setUpdate an agenda entry
agenda_deleteDelete an agenda entry
agenda_searchSearch agenda entries

Email & Chat

ToolDescription
email_accountsList the connected email accounts
email_foldersList folders in a mailbox
email_folder_createCreate a mailbox folder
email_folder_renameRename a mailbox folder
email_folder_deleteDelete a mailbox folder
email_refreshSync the mailbox with the mail server
email_searchSearch messages
email_grepSearch inside message bodies with regex
email_getRead a message, with the list of its attachments
email_get_attachmentGet a file attached to a message (fetched from the mail server the first time); its content is read through getcost://upload/{uploadId}
email_setUpdate message flags (read, starred, folder)
email_batchApply an update to many messages at once
email_moveMove a message to another folder
email_createCreate a draft message
email_editEdit a draft using find/replace
email_add_attachmentAttach a file to a draft: one already in GetCost (uploadId) or the file given in a ChatGPT conversation
email_remove_attachmentRemove a file from a draft (the file itself is kept)
email_sendSend a message
channel_searchSearch chat channels
channel_createCreate a chat channel
chat_searchSearch chat messages (drafts, unread)
chat_getRead messages from a channel or user, with each message's files (read one through getcost://upload/{uploadId})
chat_sendPrepare a chat message for the user to send
chat_add_attachmentAttach 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_attachmentRemove a file from the chat message being written
note_searchList private notes, your own or a client's
note_createWrite a private note (markdown, saved immediately)
note_setChange a note's text or colours
note_deleteDelete a note

Settings, Team & Files

ToolDescription
settings_user_getRead the current user's settings
settings_profile_getRead a permission profile
settings_business_getRead a business setting
settings_business_listList the businesses you belong to
settings_business_selectSwitch your active business to another one you belong to
settings_screen_getRead screen visibility settings (omit screen for all)
settings_screen_setChange screen visibility settings
team_membersList the members of the business
upload_searchSearch uploaded files and photos by document, type, file name, date, or what was said in a video or recording
upload_createAttach a new photo or PDF to an estimate or invoice (in ChatGPT, a file attached in the conversation)
upload_deleteDelete a document photo or a Gallery photo (to keep it, use document_remove_upload)
document_add_uploadAttach a file you already have (Gallery, another document, chat, email) to an estimate or invoice - shared, not copied
document_remove_uploadTake a photo off an estimate or invoice - it moves to the Gallery, nothing is deleted
document_set_uploadChange the caption of a photo on an estimate or invoice
newsletter_subscribeSubscribe an email address to the newsletter

Financial & Reporting

ToolDescription
transaction_createRecord an expense or income
transaction_getGet transaction details
transaction_setUpdate a transaction (amount, category, tax)
transaction_deleteDelete a transaction
transaction_searchSearch and filter transactions
transaction_batchBatch update transactions matching a filter
transaction_category_listList expense/income categories
account_createCreate a bank account
account_getGet bank account details
account_setUpdate a bank account
account_searchSearch bank accounts
report_getGenerate financial reports (expenses, income, balance)

Navigation & Utilities

ToolDescription
navigateNavigate 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_tailView recent console log entries
get_logs_filterFilter console logs by level or text

Example Conversations

Examples

Once 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

Advanced

In 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 }), and businessCount - how many businesses you belong to. When you have more than one, settings_business_list lists 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.

Tip: Because the AI can see your current context, you can say things like "Add a line item for labor at $75/hour" while viewing an estimate, and it will add the item to the correct document automatically.

Troubleshooting

Help

Common Issues

ProblemSolution
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
Need help? If you are having trouble connecting, verify your setup by sending a raw HTTP request to https://www.getcost.com/mcp with the tools/list method. A successful response confirms your API key and connection are working.