Connect NMI to Claude: Streamline Merchant Apps & Payments

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

Integrating AI with a payment gateway like NMI (Network Merchants, LLC) unlocks massive operational leverage. By connecting Claude to NMI, you can automate repetitive support queries about failed payments, streamline complex merchant underwriting processes, and programmatically issue refunds using natural language.

However, giving a Large Language Model (LLM) read and write access to financial infrastructure requires an intermediary layer. Claude cannot natively communicate with NMI's REST APIs. It needs a Model Context Protocol (MCP) server to act as a translation layer. You can spend weeks building, hosting, and maintaining this custom infrastructure yourself, or you can use a managed platform like Truto to dynamically generate a secure, authenticated MCP server URL.

This guide breaks down exactly how to use Truto to generate a managed MCP server for NMI, connect it natively to Claude, and execute high-value workflows like merchant onboarding and subscription recovery.

The Engineering Reality of the NMI API

Building a custom MCP server means owning the entire API lifecycle. While the open MCP standard provides a predictable way for models to discover tools over JSON-RPC 2.0, implementing it against a payment gateway brings specific, painful challenges.

If you decide to build a custom MCP server for NMI, here are the architectural hurdles you will face:

Polymorphic Payment Objects NMI's payment endpoints expect highly specific, mutually exclusive data structures depending on the payment method. A single POST to create a sale transaction might require a raw credit card object, an ACH bank account payload, a Collect.js payment_token, or a customer_vault_id. LLMs struggle with conditionally required fields and polymorphic schemas. They will often hallucinate invalid combinations of parameters. Truto solves this by extracting strict JSON Schema definitions directly from the integration documentation, enforcing clear boundaries for the model before the API request is ever dispatched.

Complex State Machines for Merchant Onboarding NMI is widely used by Independent Software Vendors (ISVs) for sub-merchant onboarding. This requires navigating a strict state machine: discovering application "packages", submitting draft applications, generating legal consent URLs, uploading binary PDF files for KYC compliance, and pushing the state to underwriter_requested_information or submitted. Orchestrating this via custom code requires writing massive, nested tool schemas. Truto automatically generates these tools, normalizing the application payloads so Claude only sees actionable inputs.

Rate Limits and 429 Handling NMI enforces strict rate limits. If your AI agent gets stuck in a loop querying invoices, the API will return HTTP 429 errors. A critical architectural detail: Truto does not retry, throttle, or apply automatic backoff on rate limit errors. When NMI returns a 429, Truto passes that error directly back to the caller. However, Truto normalizes the upstream rate limit information into standardized IETF headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset). This means your MCP client or agent framework must inspect these headers and handle its own retry and backoff logic to prevent failing silently.

Instead of building authentication middleware, token hashing, schema generation, and pagination normalizers from scratch, you can use Truto to expose NMI as ready-to-use MCP tools.

How to Generate an NMI MCP Server with Truto

Truto creates MCP servers dynamically based on your connected integrations. There are two ways to generate an MCP server for NMI: via the Truto UI or programmatically via the API.

Method 1: Via the Truto UI

This is the fastest method for internal testing or setting up a local instance of Claude Desktop.

1. Log into Truto and navigate to your Integrated Accounts.
2. Select your connected NMI account.
3. Click on the MCP Servers tab.
4. Click Create MCP Server.
5. Select your desired configuration. You can filter tools by methods (e.g., only read operations) or apply tags to restrict access to specific resource groups.
6. Click Save and copy the generated MCP server URL. You will need this URL to connect Claude.

Method 2: Via the Truto API

For production deployments, multi-tenant AI products, or ephemeral agent sessions, you should generate MCP servers dynamically via the Truto REST API.

Send a POST request to /integrated-account/:id/mcp with your configuration payload.

const response = await fetch('https://api.truto.one/integrated-account/<nmi_account_id>/mcp', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${TRUTO_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: "NMI Merchant Onboarding Server",
    config: {
      methods: ["read", "write"], // Expose CRUD operations
      tags: ["applications", "vault"] // Limit to specific tags
    },
    expires_at: "2025-12-31T23:59:59Z" // Optional TTL
  })
});
 
const data = await response.json();
console.log(data.url); // https://api.truto.one/mcp/<secure_token>

The returned URL contains a hashed cryptographic token linked specifically to that NMI account.

Connecting the MCP Server to Claude

Once you have your MCP server URL, you must connect it to Claude. Truto MCP servers communicate via Server-Sent Events (SSE) over HTTPS, requiring zero local infrastructure.

Method A: Via the Claude UI (or ChatGPT)

If you are using a web-based client that supports remote custom connectors:

1. Open your AI client (e.g., ChatGPT or Claude Web).
2. Navigate to Settings -> Integrations -> Add MCP Server (or Settings -> Connectors -> Add in ChatGPT).
3. Paste the Truto MCP URL.
4. Save. The client will immediately execute an initialize handshake and request the tools/list.

Method B: Via Manual Config File (Claude Desktop)

To connect Claude Desktop to Truto, you must edit the claude_desktop_config.json file. Because Truto hosts the server, you do not need to build a local Node.js app. Instead, you use the official @modelcontextprotocol/server-sse proxy to route local JSON-RPC calls to the remote Truto endpoint.

Open your configuration file:

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

Add the following configuration, replacing <YOUR_TRUTO_MCP_URL> with the URL generated in the previous step:

{
  "mcpServers": {
    "nmi_truto": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "<YOUR_TRUTO_MCP_URL>"
      ]
    }
  }
}

Restart Claude Desktop. The hammer icon will appear in your prompt input, indicating that the NMI tools are ready to use.

NMI Hero Tools for Claude

Truto dynamically translates NMI's API endpoints into flat, schema-validated MCP tools. Here are six high-leverage operations you can execute with your newly connected agent.

1. Process a Sale (nmi_payments_sale)

This tool processes an authorization and capture in a single step. It is highly flexible, allowing the agent to charge an amount using raw card details, an ACH bank account, a Collect.js payment_token, or a stored customer_vault_id.

"Process a $150.00 sale for the customer using vault ID 'cust_89234'. If the transaction declines, return the exact response_text to me."

2. Vault a Customer (create_a_nmi_customer)

Before charging a user on a recurring basis, their payment details must be securely stored. This tool creates a customer in the NMI Customer Vault with billing addresses and a payment method, returning the customer_vault_id used for future charges.

"Store John Doe in the customer vault. His billing email is john@example.com and his Collect.js payment token is 'tok_xyz789'. Return the new customer vault ID."

3. Manage Recurring Billing (create_a_nmi_subscription)

NMI supports complex recurring billing logic natively. This tool attaches a customer to an existing plan (via plan_id) or defines a custom schedule inline (e.g., specifying month_frequency and day_of_month).

"Create a new subscription for vault ID 'cust_89234' on the 'Enterprise Annual' plan (plan_id: ent_annual_12). Set the subscription to start next Monday."

4. Initiate Merchant Applications (create_a_nmi_application)

For ISVs and payment facilitators, onboarding sub-merchants is a massive operational burden. This tool creates a draft application in NMI using a specific package_id, scaffolding the required fields and collections for underwriting.

"Create a new draft application for Acme Corp using the Retail Onboarding Package. Return the application ID so we can upload their tax documents."

5. Upload Underwriting Documents (nmi_applications_upload_document)

NMI requires supporting evidence (W-9s, voided checks, IDs) before a merchant account can be approved. This tool attaches a binary file to an application while it is in the draft or underwriter_requested_information state.

"Upload the provided voided check image as a supporting document to application app_341c7b5b432a3158 under the document type 'Bank Statement'."

6. Submit Applications (nmi_applications_submit)

Once all fields are populated and documents are uploaded, this tool moves the application out of draft status and submits it directly for underwriting review.

"Submit application app_341c7b5b432a3158 for underwriting review now that all required documents are attached. Let me know the new status code."

To view the complete inventory of NMI tools, including endpoints for webhooks, embedded components, and detailed transaction filtering, visit the NMI integration page.

Workflows in Action

Individual tools are useful, but the real power of an MCP server emerges when Claude chains them together to automate multi-step workflows. Here are two real-world examples.

Workflow 1: End-to-End Sub-Merchant Onboarding

For B2B SaaS platforms acting as payment facilitators, onboarding new merchants involves tedious data entry and document management. Claude can handle the entire setup sequence.

"We just signed Acme Corp. Create a new merchant application for them using our standard Retail package. Fill in their basic company info, generate the legal consent link for their signature, and once that's prepped, submit the draft application to underwriting."

Tool Execution Sequence:

1. list_all_nmi_packages - Claude queries available packages to find the ID for the "Retail" package.
2. create_a_nmi_application - Claude drafts the application with the package_id and Acme Corp's data, receiving an application_id.
3. nmi_applications_get_legal_consent - Claude requests the widget URL required for the merchant's signature.
4. nmi_applications_submit - Claude triggers the submission to the underwriting queue.

Result: The user receives a confirmation that the application is under review, alongside the specific legal consent URL to forward to the merchant.

sequenceDiagram
  participant User as User / Agent
  participant Claude as Claude Desktop
  participant Truto as Truto MCP Server
  participant NMI as NMI API

  User->>Claude: "Onboard Acme Corp..."
  Claude->>Truto: call list_all_nmi_packages
  Truto->>NMI: GET /applications/packages
  NMI-->>Truto: Packages JSON
  Truto-->>Claude: Package ID (pkg_123)
  
  Claude->>Truto: call create_a_nmi_application(pkg_123, data)
  Truto->>NMI: POST /applications
  NMI-->>Truto: Application ID (app_456)
  Truto-->>Claude: Draft Created
  
  Claude->>Truto: call nmi_applications_submit(app_456)
  Truto->>NMI: POST /applications/app_456/submit
  NMI-->>Truto: Status: Submitted
  Truto-->>Claude: Success
  Claude-->>User: "Acme Corp has been submitted..."

Workflow 2: Subscription Recovery and Immediate Billing

Customer support teams waste hours manually updating expired credit cards in payment gateways. Claude can look up the user, update the vault, and trigger a catch-up payment instantly.

"Customer vault ID 'cust_89234' just provided a new Collect.js payment token ('tok_abc123'). Update their billing profile with this token, and immediately process a $50.00 sale to cover their missed invoice from last week."

Tool Execution Sequence:

1. update_a_nmi_customer_by_id - Claude patches the customer vault record, replacing the old card with the new payment_token.
2. nmi_payments_sale - Claude executes a $50.00 charge against the updated customer_vault_id.

Result: Claude responds with the exact authorization code and transaction ID for the $50.00 charge, confirming that the customer's vault is securely updated for future subscription cycles.

Security and Access Control

Exposing payment infrastructure to an LLM requires strict boundaries. Truto provides several mechanisms to lock down your NMI MCP server before Claude ever makes a request:

• Method Filtering: Configure the server using config.methods (e.g., ["read"]) to explicitly block Claude from executing create, update, or delete operations, ensuring the agent acts in a strict read-only capacity.
• Tag Filtering: Use config.tags to limit the server's scope. For example, applying a "vault" tag ensures the LLM can manage customer profiles but cannot touch merchant applications or fee schedules.
• Ephemeral Servers: Set an expires_at timestamp when creating the server. Once the timestamp passes, the server URL automatically self-destructs, making it perfect for short-lived CI/CD jobs or temporary agent sessions.
• Double Authentication: By setting require_api_token_auth: true, possession of the MCP URL is no longer enough. The client must also pass a valid Truto API token in the Authorization header to execute tools.

Final Thoughts

Connecting NMI to Claude transforms complex payment and underwriting operations into natural language workflows. By utilizing Truto's dynamic MCP server generation, engineering teams can bypass the boilerplate of OAuth token management, pagination normalizers, and polymorphic JSON schema translation.

Whether your agents are triaging support tickets for failed payments or fully automating sub-merchant underwriting pipelines, a managed integration layer ensures that your LLM has safe, strictly typed, and reliable access to NMI's critical financial infrastructure.