Connect Qomon to Claude: Track Mobilization and Contact Interactions

If your team needs to connect Qomon to Claude to track mobilization actions, log contact interactions, or manage transaction bundles, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's tool calls and Qomon's REST API. You can either build and maintain this infrastructure 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 /connect-qomon-to-chatgpt-manage-contacts-donors-and-teams/ or explore our broader architectural overview on /connect-qomon-to-ai-agents-automate-finances-upserts-and-team-comms/.

Giving a Large Language Model (LLM) read and write access to a specialized organizing and mobilization platform like Qomon is an engineering challenge. You have to handle authentication lifecycles, map massive JSON schemas to MCP tool definitions, and deal with Qomon's specific data structures for interactions, tags, and financial bundles. Every time Qomon updates an endpoint, you have to update your server code, redeploy, and test the integration.

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

The Engineering Reality of the Qomon API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools, the reality of implementing it against specialized B2B APIs is painful. Qomon is built for grassroots organizing, political campaigns, and non-profit mobilization. Its API reflects the complexity of managing physical actions, asynchronous data ingestion, and bundled financial transactions.

If you decide to build a custom Qomon MCP server, here are the specific integration challenges you will face:

Asynchronous Upsert Logic Qomon handles contact ingestion at scale using an asynchronous upsert pattern. When you call the contact upsert endpoint, Qomon attempts to match the record against an internal ID, a nationbuilderid, an external_id, an email, or a name and address combination. The API returns a 202 Accepted response with an empty body, meaning the actual processing happens in the background. If you hand this endpoint directly to an LLM without proper schema documentation, the model will hallucinate a response body or assume the operation failed because it didn't receive a standard 201 Created JSON payload.

Additive Transaction Bundles In Qomon, financial records - donations, memberships, and standard transactions - are grouped into "Transaction Bundles". The update logic for a transaction bundle is additive and heavily dependent on IDs. If you omit an item from the array during an update, it remains unchanged. If you include an item with an ID, it updates that specific item. If you include an item without an ID, Qomon creates a new one. A poorly instructed LLM might attempt a full replacement (PUT behavior) on an additive endpoint, resulting in massively duplicated financial records in your customer's space.

Advanced Condition-Based Searching Searching contacts in Qomon is not a matter of passing a simple ?q=name query parameter. The search API requires a deeply nested advanced_search JSON payload that constructs AND/OR logical trees across personal info, addresses, custom fields, tags, and financial activity. Building an MCP tool definition that successfully teaches an LLM how to construct this specific JSON DSL (Domain Specific Language) requires meticulous JSON Schema generation and explicit system prompts.

Creating the Qomon MCP Server

Truto solves these architectural challenges by dynamically generating MCP tools based on Qomon's underlying API schemas and documentation. Because Truto normalizes the authentication and handles the proxy routing, you only need to generate a single URL to give Claude full access to a connected Qomon space.

You can generate this server via the Truto UI or programmatically via the Truto API.

Method 1: Via the Truto UI

For internal tooling or quick experimentation, the Truto dashboard provides a point-and-click interface to generate an MCP server.

1. Log in to your Truto dashboard and navigate to your Integrated Accounts.
2. Select the specific Qomon integrated account you want to connect to Claude.
3. Click on the MCP Servers tab.
4. Click Create MCP Server.
5. Select your desired configuration (e.g., restrict the server to only "read" operations, or filter by specific tags like "contacts" or "finance").
6. Click Generate, and copy the resulting MCP server URL.

Method 2: Via the Truto API

For production use cases where you are provisioning AI agents programmatically on behalf of your customers, you can generate the MCP server via the Truto REST API.

When you make a POST request to /integrated-account/:id/mcp, Truto validates the underlying Qomon tools, generates a secure token, hashes it for secure storage, and returns a ready-to-use URL.

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

The response contains the secure URL that Claude will use to communicate with the server:

{
  "id": "mcp_abc123",
  "name": "Claude Mobilization Agent",
  "url": "https://api.truto.one/mcp/abc123def456ghi789",
  "config": {
    "methods": ["read", "write", "custom"]
  }
}

Connecting Qomon to Claude

Once you have your Truto MCP server URL, connecting it to Claude takes less than a minute. You can configure this through the Claude UI or by editing the Desktop configuration file directly.

Method 1: Via the Claude UI

If you are using Claude Desktop or an enterprise workspace that supports visual connector management:

1. Open Claude Settings.
2. Navigate to the Integrations or Connectors section.
3. Click Add MCP Server.
4. Paste the Truto MCP URL (e.g., https://api.truto.one/mcp/abc123def456ghi789).
5. Click Add. Claude will automatically perform a handshake with the server and discover the available Qomon tools.

Method 2: Via Manual Configuration File

For developers using the standard Claude Desktop app, you can add the server by modifying your claude_desktop_config.json file. Truto's MCP servers operate over standard HTTP Server-Sent Events (SSE), so we use the @modelcontextprotocol/server-sse package as the transport layer.

Update your configuration file (located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows):

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

Restart Claude Desktop. The agent will read the configuration, connect to the Truto URL, and populate its context window with the Qomon tools.

Qomon MCP Hero Tools

When Claude connects to the Truto MCP server, it dynamically loads tool definitions based on the underlying Qomon API documentation. Truto maps Qomon's REST resources into descriptive, snake_case tool names with strictly typed JSON schemas for both query parameters and request bodies.

Here are the highest-leverage tools available for Qomon mobilization and operational workflows.

create_a_qomon_contacts_upsert

This is the most efficient way to ingest field data or external lists into Qomon. The tool operates asynchronously, searching for an existing contact based on multiple fallback identifiers (ID, external ID, NationBuilder ID, email, or name/address). If a match is found, it updates the record; otherwise, it creates a new one.

Contextual usage notes: Because this endpoint returns an empty 202 Accepted response, the LLM is instructed not to wait for a full contact object in the response body. It is ideal for batch ingestion workflows.

"I have a CSV export of 50 new event attendees. Upsert these records into Qomon. Map their 'Voter File ID' to the external_id field. If they already exist, just update their address. If they are new, create them."

list_all_qomon_search_contacts

This tool unlocks Qomon's advanced search capabilities. Instead of basic filtering, it allows the LLM to construct complex JSON queries to find contacts based on demographic info, tags, locations, and financial activity.

Contextual usage notes: The tool requires an advanced_search object. Claude understands how to format this object based on the JSON Schema provided by the MCP server, enabling highly specific cohort queries.

"Find all contacts in Qomon who have the tag '2026_volunteer', live in postal code '90210', and have not made a donation in the last six months. Return their IDs and email addresses."

create_a_qomon_transaction_bundle

This tool groups one or more transactions, memberships, and donations into a single financial bundle. It is critical for reconciliation workflows where a single payment covers multiple line items (e.g., a $100 charge that is split into a $20 membership and an $80 donation).

Contextual usage notes: The payload requires at least one transaction inside the data.transactions array. The LLM can dynamically assign campaign codes and payment methods to the bundle based on conversational context.

"Create a new transaction bundle for contact ID 8492. They paid $100 via credit card today. Allocate $20 of that to a new membership, and the remaining $80 as a general donation under the campaign code 'EOY_DRIVE'."

list_all_qomon_actions

This tool lists mobilization actions (canvassing runs, phone banks, events) along with aggregate metrics like the number of contacts reached and visits declared. It is essential for generating daily or weekly field reports.

Contextual usage notes: The tool supports offset pagination. Truto automatically manages the schema for limits and offsets, instructing the LLM to paginate through the results if it needs to build a comprehensive report.

"Pull all mobilization actions from Qomon for the past 7 days. Summarize the total number of visits declared across all active canvassing campaigns and tell me which team had the highest completion rate."

create_a_qomon_contact_interaction

Interactions log the touchpoints between your organizing team and your contacts (calls, letters, meetings, SMS, emails). This tool requires a contact ID and a date of event, and allows you to attach specific interaction tags.

Contextual usage notes: This tool is frequently chained with contact search. The LLM will first find a contact, extract their ID, and then log the interaction against that ID.

"Log a phone call interaction for Jane Doe (email: jane@example.com). Note that we spoke today, she was highly supportive, and she agreed to put a yard sign up this weekend. Tag the interaction with 'yard_sign_agreed'."

To view the complete inventory of available Qomon tools, including endpoints for teams, forms, and custom fields, visit the Qomon integration page.

Workflows in Action

Exposing individual tools to Claude is useful, but the true power of MCP lies in agentic orchestration - allowing the LLM to string multiple API calls together to accomplish complex, multi-step tasks.

Here are two concrete examples of how personas interact with the Qomon MCP server in production.

Workflow 1: Post-Canvassing Data Entry

Field organizers often finish a shift with raw notes or spreadsheet rows that need to be parsed, matched to existing records, and logged as specific interactions.

Prompt: "I just finished my shift. Here are my notes: I spoke with Marcus Holloway at 123 Main St. He's a strong supporter and wants to volunteer. I also talked to Sarah Jenkins (sarah.j@email.com); she's undecided but took our literature. Please update their records and log the interactions."

Execution Steps:

1. Claude calls create_a_qomon_contacts_upsert for Marcus, matching on his name and address, setting his tag to "strong_supporter" and "wants_to_volunteer".
2. Claude calls create_a_qomon_contacts_upsert for Sarah, matching on her email, updating her tags.
3. Claude calls list_all_qomon_search_contacts to retrieve the newly upserted IDs for Marcus and Sarah.
4. Claude calls create_a_qomon_contact_interaction for Marcus, logging a "meeting" interaction with the notes.
5. Claude calls create_a_qomon_contact_interaction for Sarah, logging a "meeting" interaction noting she took literature.

Result: The user receives a conversational confirmation that both contacts were successfully upserted and their interactions were securely logged in the Qomon database.

sequenceDiagram
    participant User
    participant Claude as Claude Desktop
    participant MCP as Truto MCP Server
    participant Qomon as Qomon API

    User->>Claude: "Upsert Marcus and Sarah, log interactions..."
    
    Claude->>MCP: Call create_a_qomon_contacts_upsert (Marcus)
    MCP->>Qomon: POST /v1/contacts/upsert
    Qomon-->>MCP: 202 Accepted
    MCP-->>Claude: Success (Async)

    Claude->>MCP: Call create_a_qomon_contacts_upsert (Sarah)
    MCP->>Qomon: POST /v1/contacts/upsert
    Qomon-->>MCP: 202 Accepted
    MCP-->>Claude: Success (Async)

    Claude->>MCP: Call list_all_qomon_search_contacts
    MCP->>Qomon: POST /v1/contacts/advanced_search
    Qomon-->>MCP: [Contact IDs]
    MCP-->>Claude: Returns IDs

    Claude->>MCP: Call create_a_qomon_contact_interaction
    MCP->>Qomon: POST /v1/interactions
    Qomon-->>MCP: Interaction Created
    MCP-->>Claude: Success

    Claude-->>User: "Records updated and interactions logged."

Workflow 2: Financial Reconciliation

Operations managers frequently need to reconcile bank deposits with Qomon data, requiring them to search for donors and bundle complex transactions.

Prompt: "We received a wire transfer for $500 from 'Acme Corp' (email: billing@acme.com). Please record this in Qomon. Allocate $100 to our 'Corporate Tier 1' membership, and the remaining $400 as a general donation under the 'Q4_GALA' campaign."

Execution Steps:

1. Claude calls list_all_qomon_search_contacts querying for the email billing@acme.com to retrieve the contact ID.
2. Claude calls list_all_qomon_membership_prices to find the specific ID for the "Corporate Tier 1" membership.
3. Claude calls create_a_qomon_transaction_bundle, passing the contact ID. It structures the payload to include a transaction for $500, a membership object for $100 (referencing the price ID), and a donation object for $400 tagged with code_campaign: "Q4_GALA".

Result: The manager gets confirmation that the bundle was created, correctly associating the membership and donation to the exact contact record without manual data entry.

Handling Rate Limits and Retries

When deploying AI agents that make rapid, sequential calls to third-party systems, handling API rate limits is critical. Qomon enforces rate limits to protect its infrastructure.

It is important to understand that Truto does not retry, throttle, or apply backoff on rate limit errors. If your agent executes a loop that exceeds Qomon's limits, Qomon will return an HTTP 429 Too Many Requests status. Truto passes this 429 error directly back to the caller (Claude).

However, Truto normalizes the upstream rate limit information into standardized HTTP headers, regardless of how the underlying API formats them. Truto injects:

• ratelimit-limit
• ratelimit-remaining
• ratelimit-reset

Because these headers follow the IETF specification, the MCP client or the LLM orchestration framework is responsible for reading the ratelimit-reset header, pausing execution, and retrying the tool call once the limit window has cleared.

Security and Access Control

Granting an LLM autonomous access to a database containing PII and financial records requires strict governance. Truto provides several configuration layers to secure your MCP servers:

• Method Filtering: When generating the server, you can pass config: { methods: ["read"] }. This restricts the server to only get and list operations, ensuring Claude can query data for analysis but cannot mutate, delete, or create records.
• Tag Filtering: You can restrict the toolset to specific functional areas using tags. Passing config: { tags: ["finance"] } ensures Claude only sees tools related to transactions and donations, hiding standard contact management tools.
• Extra Authentication: By default, possession of the MCP URL grants access. By setting require_api_token_auth: true, Truto requires the connecting client to pass a valid Truto API token in the Authorization header, enforcing identity validation.
• Automatic Expiration: You can set an expires_at timestamp. Once the timestamp passes, the server URL is automatically invalidated and the underlying tokens are purged, which is ideal for temporary contractor access or ephemeral agent sessions.

By leveraging Truto's dynamic MCP server generation, engineering teams can bypass the heavy lifting of maintaining custom integration code, dealing with schema mappings, and handling OAuth lifecycles. Instead, you can focus entirely on prompting your agents and designing the mobilization workflows that actually drive value for your users.