Connect Podium to Claude: Manage Invoices, Payments, and Products

If you need to connect Podium to Claude to automate text messaging workflows, invoice generation, payment processing, or review solicitation, you need a Model Context Protocol (MCP) server. This infrastructure layer acts as a JSON-RPC 2.0 translator between Claude's tool-calling capabilities and Podium's REST API. You can either build, host, and maintain this server yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL.

If your team uses ChatGPT, check out our guide on connecting Podium to ChatGPT or explore our broader architectural overview on connecting Podium to AI Agents.

Podium is the operational backbone for thousands of local businesses, handling everything from CRM and reputation management to payment processing. Giving a Large Language Model (LLM) read and write access to these systems is a massive engineering undertaking. You have to handle OAuth 2.0 token refreshes, map strict API schemas into MCP tool definitions, and deal with Podium's location-scoped data models. Every time Podium updates a schema or enforces a new limit, your internal integration code breaks.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Podium, connect it natively to Claude, and execute complex local business workflows using natural language.

The Engineering Reality of the Podium API

A custom MCP server is a self-hosted integration middleware. While the open MCP standard provides a predictable way for Claude to discover and invoke tools, the reality of implementing it against vendor APIs is painful. You are not just integrating "Podium" - you are integrating an ecosystem designed around multi-location business management, strict state machines, and stringent rate limits.

If you decide to build a custom MCP server for Podium, you own the entire API lifecycle. Here are the specific architectural challenges you will face:

Location-Scoped Architecture Podium's API architecture is heavily scoped by location. Almost every consequential action - creating an invoice, sending a message, or pulling reviews - requires a locationUid. You cannot simply ask the API for "all invoices for a customer." The LLM must first understand the organizational hierarchy, query the correct location, and pass that locationUid into subsequent write requests. If you expose raw endpoints to Claude without context, the model will frequently hallucinate UIDs or omit the location parameter entirely, resulting in 400 Bad Request errors.

Complex State Machines for Invoices and Payments Podium enforces strict state transitions on financial objects. An invoice can only be canceled if it is in the created state. It can only be refunded if it is in the paid state. If your AI agent attempts to refund a pending invoice, the API will reject the request. Your MCP server must either validate state locally or clearly surface Podium's error messages to the LLM so it can reason about why an operation failed and attempt a remediation path.

Rate Limits and 429 Handling Podium enforces strict rate limits, particularly around messaging. The messaging API is throttled at 10 requests per minute. If your AI agent attempts a bulk broadcast operation, you will hit a 429 Too Many Requests error almost immediately. Truto normalizes Podium's upstream rate limit information into standardized HTTP headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. Crucially, Truto does not absorb, retry, or throttle rate limit errors. When Podium returns a 429, Truto passes that error directly to the caller. The caller (Claude or your custom AI agent) is fully responsible for reading the headers and implementing its own retry logic with exponential backoff.

Instead of building this infrastructure from scratch, Truto normalizes authentication, pagination, and error handling, exposing Podium's endpoints as ready-to-use MCP tools.

How to Generate a Podium MCP Server with Truto

Truto dynamically derives MCP tools directly from Podium's integration resources and documentation schemas. Tools are not cached or manually coded; they are generated on the fly when the MCP client requests them. This ensures your AI agent always has the most up-to-date schema definitions.

Each MCP server in Truto is scoped to a single integrated account (a specific tenant's connected Podium instance). The resulting server URL contains a cryptographic token that securely encapsulates the authentication state.

There are two ways to generate this server.

Method 1: Via the Truto UI

For administrators setting up Claude Desktop for internal use, the UI is the fastest path.

1. Log into your Truto dashboard and navigate to your connected Podium Integrated Account.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Configure the server name (e.g., "Podium Billing and Support"). You can optionally filter the available tools by HTTP method (e.g., only read methods) or by tags (e.g., only invoices).
5. Click Create and copy the generated MCP Server URL (it will look like https://api.truto.one/mcp/a1b2c3d4...).

Method 2: Via the Truto API

For developers programmatically provisioning MCP servers for their own end-users, you can call the Truto REST API. This generates the server record, stores the token in Cloudflare KV, and returns the endpoint.

Endpoint: POST /integrated-account/:id/mcp

curl -X POST https://api.truto.one/integrated-account/YOUR_ACCOUNT_ID/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Podium Operations Agent",
    "config": {
      "methods": ["read", "write"],
      "tags": ["invoices", "messages", "locations"]
    },
    "expires_at": "2026-12-31T23:59:59Z"
  }'

The response will return a secure, ready-to-use URL:

{
  "id": "mcp_01H...",
  "name": "Podium Operations Agent",
  "config": {
    "methods": ["read", "write"],
    "tags": ["invoices", "messages", "locations"]
  },
  "expires_at": "2026-12-31T23:59:59.000Z",
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f6g7h8..."
}

How to Connect the Podium MCP Server to Claude

Once you have the URL, you need to register it with your LLM client. Claude communicates with remote MCP servers over Server-Sent Events (SSE) via HTTP POST.

Method 1: Via the Claude UI

If you are using Claude on a Team or Enterprise plan (or ChatGPT with custom connectors), you can add the URL directly through the interface.

1. Open Claude and navigate to Settings -> Integrations.
2. Click Add MCP Server (or Custom Connector).
3. Paste the Truto MCP URL.
4. Click Connect.

Claude will immediately send an initialize JSON-RPC request to the URL, handshake with Truto, and pull down the complete list of Podium tools.

Method 2: Via Manual Configuration File

If you are running Claude Desktop locally or managing configuration via code, you can define the server in your claude_desktop_config.json file. Because Truto provides an SSE endpoint, you must use the official @modelcontextprotocol/server-sse proxy package to bridge Claude's local standard-input/output transport to the remote HTTP URL.

Locate your Claude config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the Podium server definition:

{
  "mcpServers": {
    "podium": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "--url",
        "https://api.truto.one/mcp/a1b2c3d4e5f6g7h8..."
      ]
    }
  }
}

Restart Claude Desktop. The application will execute the proxy command, establish the connection to Truto, and the Podium tools will appear as a hammer icon in your input bar.

Hero Tools for Podium Automation

Truto exposes Podium's REST endpoints as highly structured MCP tools. Each tool includes strict query and body schemas derived from Podium's documentation, guiding Claude on exactly what parameters to pass. Here are the highest-leverage operations for local business automation.

list_all_podium_locations

Because almost all operations in Podium require a location UID, this is the foundational tool. Your AI agent must invoke this to map a human-readable business name (e.g., "Downtown Shop") to its corresponding uid.

"List all of our registered Podium locations. We need the unique ID for the 'Springfield Auto' shop to process a refund."

create_a_podium_invoice

Generates an invoice and a secure payment link. It requires channelIdentifier, customerName, invoiceNumber, lineItems, and locationUid. By omitting the readerUid, you tell the API to generate a card-not-present digital invoice.

"Draft a new invoice for John Smith for $250.00 for 'Plumbing Repair' at the downtown location. Return the payment link once generated."

podium_invoices_refund

Processes a refund for a paid invoice. This highlights the importance of the MCP server returning clean error messages: if Claude tries to refund an unpaid invoice, Truto will pass the 400 error back, and Claude can inform the user.

"Process a full refund for invoice ID inv_883742. The customer reported the service was canceled."

list_all_podium_reviews

Pulls recent feedback from connected review sites (Google, Facebook, etc.). The tool returns the review body, rating, site name, and whether the review requires a response.

"Pull the last 10 reviews for the westside clinic. Filter for any reviews under 3 stars that currently need a response."

create_a_podium_review_invite

Generates a unique review invitation link for a specific customer. Podium strictly warns against sending the same link to multiple contacts; Claude can use this tool to generate unique links iteratively.

"Generate a new review invite link for Sarah Connor. Once generated, draft a polite SMS asking her to review her recent visit."

podium_conversation_messages_send

Sends an outbound message to a contact. Requires the message body, channel, and locationUid. This tool executes through Truto's proxy architecture, ensuring the payload exactly matches Podium's required schema.

"Send a text message to 555-0199 confirming their appointment tomorrow at 10 AM. Use the southside location UID."

For the complete tool inventory, detailed JSON schemas, and parameter requirements, visit the Podium integration page.

Workflows in Action

Giving Claude access to Podium tools allows you to replace rigid scripts with dynamic, goal-oriented workflows. The model autonomously sequences API calls, parses responses, and handles missing context.

Scenario 1: Invoice Generation and SMS Delivery

Local businesses frequently need to invoice customers immediately after service delivery. Instead of logging into the dashboard, an admin can instruct Claude to handle the entire lifecycle.

"Create an invoice for $450 for 'HVAC Maintenance' for Alice Wonderland at the Northside Branch. Once the invoice is generated, text her the payment link to her phone number on file."

1. list_all_podium_locations: Claude searches the locations to find the UID for the "Northside Branch".
2. list_all_podium_contacts: Claude searches for "Alice Wonderland" to retrieve her contact UID and phone number details.
3. create_a_podium_invoice: Claude passes the location UID, line items, and customer details to generate the invoice. The API returns the invoice object, which contains the short URL for payment.
4. podium_conversation_messages_send: Claude drafts a polite message including the payment URL and sends it to Alice's channel identifier.

Claude responds: "I have generated Invoice #1001 for $450.00. The payment link has been successfully sent to Alice via SMS."

Scenario 2: Dispute Resolution and Automated Refunds

Handling customer disputes requires verifying payment status and issuing refunds across different systems.

"A customer named Bob Builder at the Main St location called to cancel his order. Find his last invoice. If it's paid, refund it fully. If it's unpaid, just cancel it."

1. list_all_podium_locations: Claude finds the UID for "Main St".
2. list_all_podium_invoices: Claude queries recent invoices for "Bob Builder" at the Main St location.
3. Conditional Logic: Claude inspects the status field of the returned invoice.
4. podium_invoices_refund (or podium_invoices_cancel): Based on the state, Claude invokes the correct endpoint. If the refund is processed, it notes the settledAt timestamp.

Claude responds: "Bob Builder's last invoice (INV-099) was already paid. I have issued a full refund. The refund was successfully processed."

Scenario 3: Negative Review Triage

Reputation management requires constant monitoring. You can use Claude to actively monitor and draft responses to negative feedback.

"Check our recent reviews across all locations. Find any 1-star or 2-star reviews from the last week that we haven't responded to. Draft a polite, empathetic response for each one and pause for my approval."

1. list_all_podium_locations: Claude gets all location context.
2. list_all_podium_reviews: Claude paginates through recent reviews, applying internal filters to isolate low ratings where needsResponse is true.
3. Content Generation: Claude uses its LLM reasoning capabilities to read the customer's complaint and draft a contextual, de-escalating response.
4. User Interaction: Claude presents the drafts to the user in the chat.
5. (Upon user approval) create_a_podium_review_response: Claude writes the responses back to the Podium API.

Security and Access Control

Exposing a billing and communications API to an LLM introduces significant risk. If a prompt injection tricks the model, it could theoretically send spam texts or cancel active invoices. Truto provides four layers of security to lock down MCP server capabilities at the infrastructure level.

• Method Filtering (config.methods): Restrict the MCP server to specific operation types. Setting methods: ["read"] ensures the LLM can only execute get and list operations. It physically cannot invoke create or update tools, making it safe for analytics and reporting use cases.
• Tag Filtering (config.tags): Scope the server to specific functional domains. Setting tags: ["invoices", "payments"] prevents the LLM from accessing messaging, reviews, or user directory endpoints.
• Secondary Authentication (require_api_token_auth): By default, possession of the MCP URL grants access to the tools. Setting this flag to true requires the MCP client to also pass a valid Truto API token in the Authorization header. This prevents unauthorized execution if the URL is leaked in a log file.
• Time-to-Live (expires_at): Ideal for temporary agent workflows. You can set an exact ISO 8601 datetime. Once the expiration passes, Cloudflare KV automatically drops the token and a background worker deletes the server configuration. The URL becomes instantly invalid.

Architecting AI Agent Integrations

Building AI features is no longer constrained by the intelligence of the model; it is constrained by the integrations connecting the model to your user's data. If you choose to build a custom Podium MCP server, you commit your engineering team to maintaining OAuth lifecycles, monitoring undocumented API changes, and rewriting massive JSON schemas every time a new endpoint is released.

Truto abstracts this away. By dynamically deriving tool schemas from live documentation and executing requests through a hardened proxy API architecture, Truto ensures your agents always have reliable, type-safe access to Podium.