justifi-mcp by waycool - MCP Server

JustiFi MCP Server for Support Team

A Model Context Protocol (MCP) server that provides support tools for JustiFi's payment platform. This server enables support staff to efficiently search accounts, investigate payment issues, check onboarding status, and analyze transaction failures.

Features

Sub-Account Management

Search Sub-Accounts: Find customer accounts with partial information (name, email, business name)
Account Details: Get comprehensive account information and settings
Onboarding Status: Check onboarding progress and missing requirements

Payment Investigation

Payment Search: Find transactions with advanced filtering (status, amount, date range)
Payment Details: Get full transaction information including fees and timeline
Failure Analysis: Automated analysis of payment failures with suggested solutions

Payout Management

Payout Search: Find payout records with status and date filtering
Payout Details: Check payout timeline, fees, and bank account information
Balance Checking: View available and pending balances

Logging & Debugging

Transaction Logs: Search event logs for payments, payouts, and account changes
Platform Wallet: Check wallet account settings and status

Installation

Clone this repository
Install dependencies:

npm install

Build the project:

npm run build

Configuration

Environment Variables

Set the following environment variables:

export JUSTIFI_CLIENT_ID="your_client_id_here"
export JUSTIFI_CLIENT_SECRET="your_client_secret_here"
# Optional: Override API base URL (defaults to https://api.justifi.ai)
export JUSTIFI_API_BASE_URL="https://api.justifi.ai"

Note: JustiFi uses OAuth2 client credentials flow. The server automatically:

Exchanges your client credentials for access tokens (valid for 24 hours)
Handles token refresh when tokens expire
Retries requests with fresh tokens on authentication failures

Testing Authentication:

# Test your credentials before using the MCP server
node test-auth.js

Finding the Correct API URL

If you get DNS resolution errors, test available endpoints:

node test-api-urls.js

Common working endpoints:

https://api.justifi.ai (default)
https://justifi-api.herokuapp.com (alternative)

Claude Desktop Integration

Add this server to your Claude Desktop configuration file:

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

{
  "mcpServers": {
    "justifi-support": {
      "command": "node",
      "args": ["path/to/justifi-mcp/dist/index.js"],
      "env": {
        "JUSTIFI_CLIENT_ID": "your_client_id_here",
        "JUSTIFI_CLIENT_SECRET": "your_client_secret_here"
      }
    }
  }
}

Available Tools

1. search_sub_accounts

Search for sub-accounts using partial information.

Parameters:

query (optional): Search term (name, email, business name)
status (optional): Filter by status (active, inactive, suspended)
limit (optional): Number of results (default: 20, max: 100)

Example Usage:

"Find all accounts with email containing 'john@'"
"Show me inactive sub-accounts"
"Search for accounts with 'Acme' in the name"

2. get_sub_account_details

Get comprehensive information about a specific sub-account.

Parameters:

sub_account_id (required): JustiFi sub-account ID

Returns: Account info, onboarding status, enabled features, settings, business details

3. get_sub_account_onboarding_status

Check onboarding progress for a sub-account.

Parameters:

sub_account_id (required): JustiFi sub-account ID

Returns: Completion status, completed/required steps, missing requirements

4. search_payments

Search payment transactions with advanced filtering.

Parameters:

sub_account_id (optional): Filter by sub-account
status (optional): Payment status (pending, authorized, captured, failed, cancelled, refunded)
amount_min/amount_max (optional): Amount range in cents
created_after/created_before (optional): Date range (ISO format)
payment_method (optional): Method type (card, bank_account, digital_wallet)
limit (optional): Results limit (default: 50)

5. get_payment_details

Get comprehensive payment information.

Parameters:

payment_id (required): JustiFi payment ID

Returns: Payment data, fees, processing timeline, refunds

6. analyze_payment_failure

Analyze failed payments with suggested solutions.

Parameters:

payment_id (required): Failed payment ID

Returns: Failure analysis, suggested customer actions, impact assessment

7. search_payouts

Search payout records.

Parameters:

sub_account_id (optional): Filter by sub-account
status (optional): Payout status (pending, in_transit, paid, failed, returned)
created_after/created_before (optional): Date range
limit (optional): Results limit (default: 50)

8. get_payout_details

Get detailed payout information.

Parameters:

payout_id (required): JustiFi payout ID

Returns: Payout data, fees, processing timeline

9. get_account_balance

Check current account balances.

Parameters:

sub_account_id (required): Sub-account ID

Returns: Available balance, pending balance, currency, last updated

10. search_transaction_logs

Search event logs for debugging.

Parameters:

sub_account_id (optional): Filter by sub-account
payment_id (optional): Filter by payment
payout_id (optional): Filter by payout
event_type (optional): Event type filter
created_after/created_before (optional): Date range
limit (optional): Results limit (default: 100)

11. get_platform_wallet_account

Check platform wallet account information.

Parameters:

sub_account_id (required): Sub-account ID

Common Support Scenarios

Scenario 1: Customer can't find their account

Use: search_sub_accounts
- Search by customer email, business name, or partial information
- Get list of matching accounts with IDs and basic info

Scenario 2: Payment failure investigation

1. Use: search_payments (filter by customer sub_account_id and failed status)
2. Use: get_payment_details (get full transaction info)
3. Use: analyze_payment_failure (get automated analysis and suggestions)
4. Use: search_transaction_logs (check related events)

Scenario 3: Onboarding issues

1. Use: get_sub_account_details (check account status)
2. Use: get_sub_account_onboarding_status (see missing requirements)

Scenario 4: Payout delays

1. Use: search_payouts (find customer's recent payouts)
2. Use: get_payout_details (check status and timeline)
3. Use: get_account_balance (verify available funds)

Development

Running in Development

npm run dev

Building

npm run build

Testing

# Start the server and test with Claude Desktop or MCP clients
npm start

Troubleshooting

DNS Resolution Errors

If you see getaddrinfo ENOTFOUND api.justifi.tech:

Test available API endpoints:

node test-api-urls.js

Set the working URL in your environment:

export JUSTIFI_API_BASE_URL="https://api.justifi.ai"
export JUSTIFI_CLIENT_ID="your_client_id_here"
export JUSTIFI_CLIENT_SECRET="your_client_secret_here"

Rebuild and restart the server:

npm run build
# Restart Claude Desktop

Authentication Errors

Verify your JUSTIFI_CLIENT_ID and JUSTIFI_CLIENT_SECRET are correct
Check if the credentials have the required permissions
Ensure you're using the production vs sandbox endpoint appropriately
Check server logs for token exchange errors

Server Won't Start

Check Node.js version (requires Node 18+)
Verify all dependencies are installed: npm install
Check the build completed: ls dist/index.js

Security Notes

API keys are passed via environment variables
The server only provides read-only access to JustiFi data
All API calls are logged for audit purposes
Network timeouts are configured to prevent hanging requests

Support

For issues with this MCP server, contact the development team. For JustiFi API issues, refer to JustiFi Documentation or contact JustiFi support at customer_success@justifi.tech.