Setting Up RefundKit MCP Server with Claude — RefundKit Blog

Introduction

The Model Context Protocol (MCP) is an open standard that lets AI models interact with external tools in a structured, type-safe way. Instead of asking an AI to construct raw HTTP requests or parse unstructured API documentation, MCP provides the model with explicit tool definitions -- including parameter schemas, descriptions, and return types -- so it can invoke tools reliably.

RefundKit provides an MCP server that exposes refund operations as tools. When connected to Claude Desktop (or any MCP-compatible client), Claude gains the ability to look up transactions, issue refunds, check refund status, and retrieve refund analytics -- all through a well-defined interface with built-in policy enforcement, rate limiting, and audit trails.

This tutorial walks through the complete setup process: installing the MCP server, configuring Claude Desktop, testing each tool, and building a practical refund assistant that can handle customer requests.

Prerequisites

Before starting, you need three things:

A RefundKit account with an API key. If you are testing, use a test-mode API key (prefixed with rk_test_). Test-mode keys interact with sandbox versions of payment processors, so no real money moves.
Claude Desktop installed on your machine. The MCP integration is available in Claude Desktop for macOS and Windows.
Node.js 18 or later installed, since the RefundKit MCP server runs as a Node.js process.

You can verify your Node.js version:

node --version
# Should output v18.x.x or later

Step 1: Install the RefundKit MCP Server

The RefundKit MCP server is distributed as an npm package. You can install it globally or run it directly with npx. For a permanent setup, global installation is cleaner:

npm install -g @refundkit/mcp-server

Verify the installation:

refundkit-mcp --version
# Should output the current version

If you prefer not to install globally, you can use npx in the Claude Desktop configuration (shown in the next step). The tradeoff is a few seconds of startup latency each time Claude launches the server.

Step 2: Configure Claude Desktop

Claude Desktop discovers MCP servers through its configuration file. The location depends on your operating system:

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

Open this file in your editor (create it if it does not exist) and add the RefundKit MCP server:

{
  "mcpServers": {
    "refundkit": {
      "command": "refundkit-mcp",
      "args": ["--stdio"],
      "env": {
        "REFUNDKIT_API_KEY": "rk_test_your_test_key_here"
      }
    }
  }
}

If you skipped the global install and want to use npx:

{
  "mcpServers": {
    "refundkit": {
      "command": "npx",
      "args": ["-y", "@refundkit/mcp-server", "--stdio"],
      "env": {
        "REFUNDKIT_API_KEY": "rk_test_your_test_key_here"
      }
    }
  }
}

A few notes about this configuration:

The --stdio flag tells the server to communicate over standard input/output, which is the transport Claude Desktop uses for local MCP servers.
The API key is passed as an environment variable, not a command-line argument, to avoid exposing it in process listings.
Use a test-mode key (rk_test_) during development. Switch to a live key (rk_live_) only when you are ready for production use.

After saving the configuration, restart Claude Desktop. You should see the RefundKit tools appear in the tool selector (the hammer icon) in the Claude Desktop interface.

Step 3: Verify the Connection

Open a new conversation in Claude Desktop and ask Claude to list its available tools. You should see the RefundKit tools in the response. You can also verify directly by asking:

"What RefundKit tools do you have access to?"

Claude should describe the available tools, which typically include:

list_transactions -- Search and retrieve transactions by customer, date range, amount, or status
get_transaction -- Get full details for a specific transaction
create_refund -- Issue a full or partial refund for a transaction
get_refund -- Check the status and details of a specific refund
list_refunds -- List refunds with filtering and pagination
get_refund_analytics -- Retrieve refund metrics and trends

If the tools do not appear, check the Claude Desktop logs for errors. Common issues include:

Invalid API key: Make sure the key starts with rk_test_ and is correctly copied with no extra whitespace.
Node.js not found: If you installed Node.js through a version manager like nvm, the path might not be available in Claude Desktop's environment. You can add a "PATH" entry to the env object in the configuration.
Server crash on startup: Run the server manually to see error output: REFUNDKIT_API_KEY=rk_test_xxx refundkit-mcp --stdio

Step 4: Test the Transaction Lookup Tool

Before testing refunds, you need transactions to refund. If you are using a test-mode API key, you can create test transactions through the RefundKit dashboard or API:

import RefundKit from '@refundkit/sdk';

const rk = new RefundKit({ apiKey: 'rk_test_your_test_key_here' });

// Create a test transaction
const transaction = await rk.transactions.create({
  amount: 4999, // $49.99 in cents
  currency: 'usd',
  customerId: 'cust_test_123',
  metadata: {
    orderId: 'order_001',
    productName: 'Annual Subscription'
  }
});

console.log('Created transaction:', transaction.id);
// Output: Created transaction: txn_test_abc123

Now ask Claude to look up this transaction:

"Look up transaction txn_test_abc123 and tell me the details."

Claude will invoke the get_transaction tool and return the transaction details, including the amount, currency, customer ID, payment processor, and metadata. This is a read-only operation with no financial impact -- a safe first test.

You can also test the search functionality:

"Show me all transactions for customer cust_test_123 from the last 30 days."

Claude will use the list_transactions tool with the appropriate filters. Verify that the results match what you expect from your test data.

Step 5: Test the Refund Tool

Now for the core functionality. Ask Claude to issue a refund:

"Refund transaction txn_test_abc123 for the full amount. The reason is customer_request."

Claude will invoke the create_refund tool. Since you are using a test-mode API key, this will create a simulated refund without moving real money. Watch for:

The tool invocation: Claude should show you the parameters it is sending (transaction ID, reason, and optionally amount).
The response: You should get back a refund object with an ID (like rfd_test_xyz789), the amount, status, and estimated arrival.
The natural language summary: Claude should translate the raw response into a human-readable summary.

Test partial refunds too:

"Issue a $15.00 refund on transaction txn_test_def456. Reason: product_issue. Note: Customer reported missing accessory."

Verify that Claude correctly converts the dollar amount to cents (1500) in the tool call, includes the reason and note, and reports the result accurately.

Testing Error Handling

Equally important is testing how Claude handles errors. Try these scenarios:

Invalid transaction ID:

"Refund transaction txn_nonexistent_123."

Claude should receive an error from the tool and communicate it clearly: "I could not find a transaction with that ID."

Already refunded transaction:

"Refund transaction txn_test_abc123 again." (if you already refunded it fully)

The tool should return a policy violation, and Claude should explain that the transaction has already been fully refunded.

Over-refund attempt:

"Refund $100.00 on transaction txn_test_abc123." (if the transaction was only $49.99)

The tool should reject this with a clear error about the refund amount exceeding the transaction amount.

Step 6: Test the Refund Status Tool

After creating a refund, test the status lookup:

"What is the status of refund rfd_test_xyz789?"

Claude will invoke the get_refund tool and return the current status. In test mode, refunds typically move to succeeded immediately. In live mode, they might stay pending for several days depending on the processor.

You can also ask for a list of all refunds:

"Show me all refunds issued today."

Claude will use the list_refunds tool with a date filter. This is useful for building dashboards and reports through natural language.

Step 7: Test the Analytics Tool

The analytics tool provides aggregate metrics about your refund operations:

"Show me refund analytics for the last 30 days."

Claude will invoke get_refund_analytics and present metrics like total refund count, total refund amount, average refund amount, refund rate (as a percentage of transactions), and breakdowns by reason and status.

This tool is particularly useful for ongoing monitoring:

"Compare refund rates this week versus last week. Are there any notable trends?"

Claude can pull analytics for both periods and provide a comparative analysis, highlighting any anomalies that might warrant investigation.

Building a Refund Assistant

With the tools verified, you can now build a practical refund assistant by giving Claude a system prompt that defines its role, policies, and behavior. Here is an example system prompt for a customer-facing refund assistant:

You are a customer support assistant for Acme Corp. You help customers
with refund requests for their purchases.

REFUND POLICIES:
- Full refunds are available within 30 days of purchase
- After 30 days, only partial refunds (up to 50%) are available
- Digital products are non-refundable after download
- Subscription refunds are prorated based on remaining days

WORKFLOW:
1. Ask for the customer's order number or email address
2. Look up their transaction using the RefundKit tools
3. Verify the refund request against the policies above
4. If eligible, process the refund and confirm the details
5. If not eligible, explain why and offer alternatives

GUIDELINES:
- Always confirm the refund amount before processing
- Include the reason category that best matches the customer's issue
- Add a note summarizing the customer's explanation
- If the refund amount exceeds $200, inform the customer that it
  requires manual review and will be processed within 24 hours
- Never process a refund without the customer explicitly requesting one

With this system prompt, Claude becomes a capable refund assistant that can handle multi-turn conversations:

Customer: "Hi, I purchased a subscription last week but I need to cancel and get a refund."

Claude: "I'd be happy to help with that. Could you provide your order number or the email address associated with your account?"

Customer: "My order number is order_12345."

Claude (uses list_transactions to find the transaction): "I found your subscription purchase from January 5th for $49.99. Since this is within 30 days of purchase, you're eligible for a full refund. Would you like me to process a full refund of $49.99?"

Customer: "Yes, please."

Claude (uses create_refund with reason: customer_request): "Your refund of $49.99 has been processed. Refund ID: rfd_abc123. You should see the funds back in your account within 5-10 business days, depending on your bank. Is there anything else I can help with?"

Advanced Configuration

Custom Tool Permissions

If you want to restrict which tools Claude can access, you can configure this in the MCP server:

{
  "mcpServers": {
    "refundkit": {
      "command": "refundkit-mcp",
      "args": [
        "--stdio",
        "--tools=list_transactions,get_transaction,get_refund,list_refunds"
      ],
      "env": {
        "REFUNDKIT_API_KEY": "rk_test_your_test_key_here"
      }
    }
  }
}

This configuration gives Claude read-only access -- it can look up transactions and refunds but cannot create new refunds. This is useful for information-only assistants that escalate refund requests to human agents.

Webhook Integration for Real-Time Updates

For production use, you will want to set up webhooks so your systems are notified when refund statuses change:

import express from 'express';
import RefundKit from '@refundkit/sdk';

const app = express();
const rk = new RefundKit({ apiKey: process.env.REFUNDKIT_API_KEY! });

app.post(
  '/webhooks/refundkit',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const signature = req.headers['refundkit-signature'] as string;

    let event;
    try {
      event = rk.webhooks.verify(
        req.body,
        signature,
        process.env.REFUNDKIT_WEBHOOK_SECRET!
      );
    } catch (err) {
      console.error('Webhook signature verification failed:', err);
      return res.status(400).send('Invalid signature');
    }

    switch (event.type) {
      case 'refund.succeeded':
        console.log(`Refund ${event.data.id} succeeded`);
        // Update your order management system
        // Send confirmation email to customer
        break;

      case 'refund.failed':
        console.log(`Refund ${event.data.id} failed: ${event.data.failureReason}`);
        // Alert your support team
        // Queue for manual retry
        break;

      case 'refund.requires_approval':
        console.log(`Refund ${event.data.id} needs approval`);
        // Notify manager via Slack/email
        break;
    }

    res.status(200).json({ received: true });
  }
);

app.listen(3000, () => console.log('Webhook server running on port 3000'));

Logging and Monitoring

In production, you should monitor your MCP server's behavior. The RefundKit MCP server supports structured logging:

{
  "mcpServers": {
    "refundkit": {
      "command": "refundkit-mcp",
      "args": [
        "--stdio",
        "--log-level=info",
        "--log-format=json"
      ],
      "env": {
        "REFUNDKIT_API_KEY": "rk_live_your_live_key_here",
        "REFUNDKIT_LOG_FILE": "/var/log/refundkit-mcp.json"
      }
    }
  }
}

Each tool invocation is logged with the request parameters (sensitive fields redacted), the response status, latency, and any errors. This gives you full observability into what Claude is doing with your refund tools.

Deploying to Production

When you are ready to move from test mode to production:

Switch to a live API key: Replace rk_test_ with rk_live_ in your configuration. Double-check that your policy rules and rate limits are configured correctly in the RefundKit dashboard before doing this.
Set up webhooks: Configure webhook endpoints for refund.succeeded, refund.failed, and refund.requires_approval events so your systems stay in sync.
Configure rate limits: In the RefundKit dashboard, set appropriate rate limits for your MCP server's API key. Start conservative -- you can always increase limits as you gain confidence in the system.
Enable approval workflows: For refunds above a certain amount, configure the system to require manual approval. This adds a human checkpoint for high-value operations.
Monitor actively: Watch refund volume, success rates, and error rates during the first few days of production use. Set up alerts for anomalies.

Troubleshooting Common Issues

Claude does not use the tools: If Claude describes what it would do instead of actually invoking the tools, try being more explicit in your prompt: "Use the RefundKit tools to look up this transaction." Also verify that the tools appear in the tool selector.

Timeout errors: The MCP server has a default timeout of 30 seconds per tool call. If your payment processor is slow, you might see timeouts. You can increase this with --timeout=60000 in the server args.

Authentication errors: If you see "Invalid API key" errors, verify that the key is correct, has the right permissions, and that there are no trailing whitespace characters in your configuration file.

Rate limit errors: If you hit rate limits during testing, wait a few minutes or adjust the limits in your RefundKit dashboard. In production, rate limits are intentional safeguards -- if you are hitting them, investigate whether the volume is expected.

Conclusion

Setting up RefundKit's MCP server with Claude Desktop gives you a powerful refund assistant in under thirty minutes. The MCP protocol handles the complexity of tool discovery, parameter validation, and structured communication, while RefundKit handles policy enforcement, multi-processor routing, and audit trails.

Start with test-mode keys to build confidence in the system, verify each tool works as expected, and gradually move toward production use. The combination of Claude's natural language understanding and RefundKit's refund infrastructure creates a system that is both user-friendly and operationally robust.