Omise Model Context Protocol (MCP) Server

The Omise Model Context Protocol (MCP) server enables seamless integration of Omise payment operations directly into AI assistants like Claude Desktop, Continue, and other MCP-compatible tools. With the MCP server, you can manage charges, customers, refunds, transfers, and more through natural language conversations.

Overview

What is Model Context Protocol (MCP)?

Model Context Protocol (MCP) is an open standard developed by Anthropic that enables AI assistants to securely connect to external data sources and tools. MCP servers expose specific capabilities that AI models can use to perform real-world actions on behalf of users.

The Omise MCP server provides a bridge between AI assistants and the Omise API, allowing you to:

Query payment data - Retrieve charges, customers, transfers, and other resources
Create transactions - Process payments, create customers, and issue refunds
Manage resources - Update customer information, cancel scheduled charges, etc.
Automate workflows - Use natural language to orchestrate complex payment operations

Key Benefits

Natural Language Interface - Interact with Omise using conversational commands
Increased Productivity - Automate routine payment operations without writing code
Secure Authentication - API keys stored locally and never sent to AI providers
Real-time Operations - Execute live payment transactions through your AI assistant
Multi-tool Support - Works with Claude Desktop, Continue, Cline, and other MCP clients

Installation

Prerequisites

Node.js 18+ - Required to run the MCP server
Omise Account - Active account with API keys
MCP-Compatible Client - Claude Desktop, Continue, or similar tool

Installing via npm

Install the Omise MCP server globally using npm:

npm install -g @omise/mcp-server

Using with npx

Alternatively, use npx to run without installation:

npx @omise/mcp-server

Verifying Installation

Check that the server is installed correctly:

omise-mcp --version

Configuration

Claude Desktop Setup

Claude Desktop is a native desktop application that supports MCP servers. To configure the Omise MCP server:

Locate Configuration File
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.json

Add Omise MCP Server

Edit the configuration file to include the Omise MCP server:

{
  "mcpServers": {
    "omise": {
      "command": "npx",
      "args": ["-y", "@omise/mcp-server"],
      "env": {
        "OMISE_SECRET_KEY": "skey_test_your_secret_key_here",
        "OMISE_PUBLIC_KEY": "pkey_test_your_public_key_here"
      }
    }
  }
}

Restart Claude Desktop

Close and reopen Claude Desktop to load the new configuration.
Verify Connection

Start a new conversation and ask: "Can you list my recent Omise charges?"

Continue (VS Code Extension) Setup

Continue is an open-source AI code assistant for VS Code. To add Omise MCP:

Open Continue Settings

In VS Code, open the Continue settings file (.continue/config.json).

Add MCP Server Configuration

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "name": "omise",
        "command": "npx",
        "args": ["-y", "@omise/mcp-server"],
        "env": {
          "OMISE_SECRET_KEY": "skey_test_your_secret_key_here",
          "OMISE_PUBLIC_KEY": "pkey_test_your_public_key_here"
        }
      }
    ]
  }
}

Reload VS Code

Reload the VS Code window to apply changes.

Cline Setup

Cline (formerly Claude Dev) is another VS Code extension supporting MCP:

Access MCP Settings

Open Cline settings in VS Code.

Add Server

Navigate to MCP Servers section and add:

{
  "omise": {
    "command": "npx",
    "args": ["-y", "@omise/mcp-server"],
    "env": {
      "OMISE_SECRET_KEY": "skey_test_your_secret_key_here",
      "OMISE_PUBLIC_KEY": "pkey_test_your_public_key_here"
    }
  }
}

Environment Variables

The Omise MCP server requires the following environment variables:

Variable	Required	Description
`OMISE_SECRET_KEY`	Yes	Your Omise secret key (starts with `skey_`)
`OMISE_PUBLIC_KEY`	No	Your Omise public key (starts with `pkey_`)
`OMISE_API_VERSION`	No	API version to use (defaults to latest)

Important: Always use test keys during development and testing.

Available Tools

The Omise MCP server exposes the following tools for AI assistants:

Charge Operations

list_charges - Retrieve a paginated list of charges
get_charge - Get details of a specific charge by ID
create_charge - Create a new charge for a payment
capture_charge - Capture a previously authorized charge
reverse_charge - Reverse an uncaptured authorized charge
update_charge - Update charge metadata

Customer Operations

list_customers - List all customers with pagination
get_customer - Retrieve a specific customer by ID
create_customer - Create a new customer profile
update_customer - Update customer information
delete_customer - Delete a customer profile

Card Operations

list_cards - List cards associated with a customer
get_card - Get details of a specific card
update_card - Update card information (name, expiration)
delete_card - Remove a card from a customer

Refund Operations

list_refunds - List all refunds for a charge
get_refund - Get details of a specific refund
create_refund - Issue a full or partial refund

Transfer Operations

list_transfers - List transfers to your bank account
get_transfer - Get details of a specific transfer
create_transfer - Create a manual transfer
update_transfer - Update transfer information

Source Operations

list_sources - List payment sources
get_source - Get details of a specific source
create_source - Create a new payment source

Balance Operations

get_balance - Retrieve current account balance
get_transaction - Get details of a transaction

Dispute Operations

list_disputes - List all disputes
get_dispute - Get details of a specific dispute
update_dispute - Update dispute information

Event Operations

list_events - List API events for webhook debugging
get_event - Get details of a specific event

Usage Examples

Example Prompts

Once configured, you can interact with Omise using natural language:

Retrieving Information:

"Show me the last 10 charges"
"What's my current account balance?"
"Get details for charge chrg_test_5v7h8gp2xqf0v0k4zy7"
"List all customers created this month"

Creating Resources:

"Create a charge for 10000 THB with card token tokn_test_123"
"Create a new customer with email customer@example.com"
"Issue a full refund for charge chrg_test_5v7h8gp2xqf0v0k4zy7"

Updating Resources:

"Update customer cust_test_123 with phone number +66812345678"
"Capture charge chrg_test_5v7h8gp2xqf0v0k4zy7"
"Add metadata order_id: 12345 to charge chrg_test_5v7h8gp2xqf0v0k4zy7"

Complex Operations:

"Find all failed charges from yesterday and list the reasons"
"Show me customers who haven't made a purchase in 30 days"
"Create a customer and charge them 5000 THB in one operation"

Conversation Flow Example

Here's a typical conversation with Claude Desktop using the Omise MCP server:

You: "Can you show me my recent charges?"

Claude: "I'll retrieve your recent charges using the Omise API."

Claude uses the list_charges tool

Claude: "Here are your 5 most recent charges:

CHG-001 - 15,000 THB - Successful - Jan 15, 2026
CHG-002 - 8,500 THB - Successful - Jan 14, 2026
CHG-003 - 12,000 THB - Failed (insufficient funds) - Jan 14, 2026
CHG-004 - 5,000 THB - Pending - Jan 13, 2026
CHG-005 - 20,000 THB - Successful - Jan 12, 2026

Would you like more details on any of these charges?"

You: "Can you refund CHG-001?"

Claude: "I'll process a full refund for CHG-001 (15,000 THB)."

Claude uses the create_refund tool

Claude: "Refund processed successfully! The 15,000 THB will be returned to the customer's card within 5-7 business days."

Code Integration Example

While MCP is designed for natural language interaction, you can also use the server programmatically:

// This is how the MCP server calls the Omise API internally
const omise = require('omise')({
  secretKey: process.env.OMISE_SECRET_KEY,
  publicKey: process.env.OMISE_PUBLIC_KEY
});

// List charges
async function listCharges(limit = 10) {
  const charges = await omise.charges.list({
    limit: limit,
    order: 'reverse_chronological'
  });
  return charges;
}

// Create a charge
async function createCharge(amount, currency, token) {
  const charge = await omise.charges.create({
    amount: amount,
    currency: currency,
    card: token
  });
  return charge;
}

Configuration Options

Advanced Server Configuration

You can customize the MCP server behavior with additional environment variables:

{
  "mcpServers": {
    "omise": {
      "command": "npx",
      "args": ["-y", "@omise/mcp-server"],
      "env": {
        "OMISE_SECRET_KEY": "skey_test_your_secret_key_here",
        "OMISE_PUBLIC_KEY": "pkey_test_your_public_key_here",
        "OMISE_API_VERSION": "2019-05-29",
        "OMISE_TIMEOUT": "30000",
        "OMISE_DEBUG": "false"
      }
    }
  }
}

Configuration Parameters

Parameter	Default	Description
`OMISE_API_VERSION`	Latest	Specific Omise API version
`OMISE_TIMEOUT`	30000	Request timeout in milliseconds
`OMISE_DEBUG`	false	Enable debug logging
`OMISE_MAX_RETRIES`	3	Maximum retry attempts for failed requests

Multiple Environment Support

You can configure separate MCP servers for test and production:

{
  "mcpServers": {
    "omise-test": {
      "command": "npx",
      "args": ["-y", "@omise/mcp-server"],
      "env": {
        "OMISE_SECRET_KEY": "skey_test_...",
        "OMISE_PUBLIC_KEY": "pkey_test_..."
      }
    },
    "omise-production": {
      "command": "npx",
      "args": ["-y", "@omise/mcp-server"],
      "env": {
        "OMISE_SECRET_KEY": "skey_live_...",
        "OMISE_PUBLIC_KEY": "pkey_live_..."
      }
    }
  }
}

Real-World Use Cases

Customer Support Automation

Support agents can use MCP to quickly handle refunds and payment issues:

Scenario: Customer requests refund for a charge

Agent: "Find charges for customer@example.com in the last 7 days"
Claude: [Lists charges]
Agent: "Issue a full refund for CHG-003 and update metadata with reason: 'customer request'"
Claude: [Processes refund and updates metadata]
Agent: "Send me the refund confirmation details"

Financial Reconciliation

Accounting teams can use MCP for end-of-day reconciliation:

"Show me all successful charges from today"
"Calculate total revenue from yesterday's transfers"
"List any failed charges that need follow-up"
"Export all refunds issued this month"

Payment Investigation

Quickly investigate payment issues through conversation:

"Why did charge chrg_test_123 fail?"
"Show me all charges for customer cust_test_456"
"Has this customer had any disputes?"
"What's the status of refund rfnd_test_789?"

Subscription Management

Manage recurring payments and subscriptions:

"Show me customers with failed charges this week"
"Create a customer with email subscriber@example.com"
"Update customer cust_test_123 with a new default card"
"List all customers without active cards"

Development and Testing

Developers can use MCP for rapid testing:

"Create 5 test charges with different amounts"
"Delete all test customers created today"
"Show me the webhook events from the last hour"
"Create a charge and immediately refund it"

Security Considerations

API Key Storage

Critical Security Practices:

Never Commit API Keys - Don't store keys in version control
Use Test Keys in Development - Always use skey_test_* keys for testing
Secure Configuration Files - Restrict file permissions on config files
Environment-Specific Keys - Use different keys for test/production
Regular Key Rotation - Rotate production keys periodically

Securing Configuration Files

Set proper file permissions on your MCP configuration:

# macOS/Linux
chmod 600 ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Verify permissions
ls -la ~/Library/Application\ Support/Claude/claude_desktop_config.json

Using Environment Variables

For enhanced security, store keys in environment variables:

# Add to ~/.zshrc or ~/.bashrc
export OMISE_SECRET_KEY="skey_test_your_secret_key"
export OMISE_PUBLIC_KEY="pkey_test_your_public_key"

Then reference in configuration:

{
  "mcpServers": {
    "omise": {
      "command": "npx",
      "args": ["-y", "@omise/mcp-server"],
      "env": {
        "OMISE_SECRET_KEY": "${OMISE_SECRET_KEY}",
        "OMISE_PUBLIC_KEY": "${OMISE_PUBLIC_KEY}"
      }
    }
  }
}

Production Considerations

When using MCP with production keys:

Audit Logging - Review all operations performed through MCP
Team Access Control - Limit who has access to production configurations
Operation Validation - Always confirm before executing destructive operations
Backup API Keys - Store backup keys securely in case rotation is needed
Monitor Usage - Track API usage through Omise Dashboard

Authentication Setup

Obtaining API Keys

Log in to Omise Dashboard

Visit dashboard.omise.co
Navigate to API Keys

Go to Settings → Keys & Credentials
Copy Keys
- Test Keys - For development (start with skey_test_ and pkey_test_)
- Live Keys - For production (start with skey_live_ and pkey_live_)
Configure MCP Server

Add keys to your MCP client configuration as shown above

Testing Authentication

Verify your authentication is working:

In Claude Desktop:

"Can you get my Omise account balance?"

Expected Response: Claude should return your account balance, confirming authentication is successful.

Troubleshooting Authentication

If authentication fails:

Verify Key Format - Ensure keys start with correct prefix
Check Quotes - Make sure keys are properly quoted in JSON
Test with Dashboard - Verify keys work in Omise Dashboard
Review Permissions - Ensure keys have necessary permissions
Check Network - Verify firewall isn't blocking Omise API

Best Practices

Development Workflow

Always Use Test Mode

Use test keys during all development and testing
Never test with live keys or real customer data

Verify Before Executing

Review charge amounts and customer details before confirming
Use descriptive metadata to track MCP-generated transactions

Handle Errors Gracefully

If an operation fails, ask Claude to explain the error
Check API documentation for error code meanings

Prompt Engineering

Write clear, specific prompts for best results:

Good Prompts:

"Show me the last 10 successful charges"
"Create a charge for 5000 THB with token tokn_test_123"
"Refund 50% of charge chrg_test_456"

Less Effective Prompts:

"Show me some charges"
"Make a payment"
"Fix that charge"

Data Management

Pagination - Request specific limits: "Show me 50 charges, not just 10"
Date Ranges - Be specific: "Show charges from January 1-15, 2026"
Filtering - Use clear criteria: "Show only failed charges"

Production Usage

Before using MCP in production:

Test Thoroughly - Verify all operations in test mode
Document Workflows - Create runbooks for common operations
Train Users - Ensure team understands capabilities and limitations
Set Boundaries - Establish guidelines for what operations require approval
Monitor Activity - Regularly review MCP-generated transactions

Troubleshooting

Common Issues

MCP Server Not Loading

Symptom: Claude Desktop doesn't show Omise tools

Solutions:

Verify configuration file syntax (valid JSON)
Check file path matches your operating system
Ensure Node.js is installed and accessible
Restart Claude Desktop completely
Check Console logs for error messages

Authentication Failures

Symptom: "Invalid API key" or authentication errors

Solutions:

Verify API keys are correct (no extra spaces)
Ensure using correct environment (test vs live keys)
Check key permissions in Omise Dashboard
Verify keys are properly quoted in JSON
Test keys directly with Omise API

Tool Execution Failures

Symptom: Operations fail with errors

Solutions:

Check error message for specific failure reason
Verify required parameters are provided
Ensure sufficient account balance for operations
Check API rate limits
Verify resource IDs are correct format

Performance Issues

Symptom: Slow response times

Solutions:

Reduce pagination limits (request fewer records)
Check internet connection
Verify Omise API status
Increase timeout settings
Restart MCP server

Debug Mode

Enable debug logging to troubleshoot issues:

{
  "mcpServers": {
    "omise": {
      "command": "npx",
      "args": ["-y", "@omise/mcp-server"],
      "env": {
        "OMISE_SECRET_KEY": "skey_test_...",
        "OMISE_DEBUG": "true"
      }
    }
  }
}

View logs:

# macOS
tail -f ~/Library/Logs/Claude/mcp-server-omise.log

# Linux
tail -f ~/.config/Claude/logs/mcp-server-omise.log

Getting Help

If issues persist:

Check Omise Status - Visit status.omise.co
Review Documentation - Check docs.omise.co
Contact Support - Email support@omise.co with:
- Error messages
- Configuration (without API keys)
- Steps to reproduce
- Debug logs

FAQ

General Questions

Q: What is the difference between MCP and direct API integration?

A: MCP provides a natural language interface to Omise APIs through AI assistants, while direct API integration requires writing code. MCP is ideal for:

One-off operations and testing
Customer support tasks
Financial reconciliation
Rapid prototyping

Direct API integration is better for:

Production payment flows
High-volume operations
Custom business logic
Full control over implementation

Q: Can I use MCP in production environments?

A: Yes, but with caution. MCP is excellent for operational tasks, customer support, and administrative operations. However, for customer-facing payment flows, use direct API integration. Always:

Use live keys only when necessary
Implement proper access controls
Audit all operations
Train users on security best practices
Monitor usage regularly

Q: Which AI assistants support the Omise MCP server?

A: The Omise MCP server works with any MCP-compatible client:

Claude Desktop - Native desktop app by Anthropic
Continue - Open-source AI code assistant for VS Code
Cline - VS Code extension (formerly Claude Dev)
Other MCP Clients - Any tool implementing the MCP standard

Q: Is my API data sent to Anthropic or OpenAI?

A: No. Your API keys are stored locally in your MCP client configuration and never sent to AI providers. The MCP server runs locally on your machine and communicates directly with Omise APIs. Only the results of operations (not your keys) are shared with the AI model.

Q: Can I use multiple Omise accounts with MCP?

A: Yes. Configure multiple MCP server instances with different names and API keys:

{
  "mcpServers": {
    "omise-account-1": {
      "command": "npx",
      "args": ["-y", "@omise/mcp-server"],
      "env": {
        "OMISE_SECRET_KEY": "skey_test_account1..."
      }
    },
    "omise-account-2": {
      "command": "npx",
      "args": ["-y", "@omise/mcp-server"],
      "env": {
        "OMISE_SECRET_KEY": "skey_test_account2..."
      }
    }
  }
}

Q: How do I update the MCP server to the latest version?

A: If using npx, the latest version is automatically used. If installed globally:

npm update -g @omise/mcp-server

Technical Questions

Q: What Node.js version is required?

A: Node.js 18 or higher is required. Check your version:

node --version

If you need to update, visit nodejs.org or use a version manager like nvm.

Q: Can I use MCP with TypeScript?

A: Yes. The MCP server is written in TypeScript and includes full type definitions. If you're building custom integrations:

import { OmiseMCPServer } from '@omise/mcp-server';

const server = new OmiseMCPServer({
  secretKey: process.env.OMISE_SECRET_KEY,
  publicKey: process.env.OMISE_PUBLIC_KEY
});

Q: How do I handle rate limiting?

A: The MCP server automatically handles rate limiting with exponential backoff. If you hit rate limits:

Reduce frequency of operations
Batch operations when possible
Increase OMISE_MAX_RETRIES setting
Contact Omise support for rate limit increases

Q: Can I customize which tools are available?

A: Not directly through configuration, but you can fork the repository and modify the tool list. This is useful for:

Restricting operations in production
Creating specialized workflows
Adding custom business logic

Q: Does MCP support webhooks?

A: The MCP server can list and retrieve webhook events, but doesn't receive real-time webhook notifications. For webhook handling, use standard webhook integration with your application.

Q: How do I test MCP without making real API calls?

A: Use Omise test keys (starting with skey_test_). Test mode provides:

Simulated payment processing
Safe testing environment
No real money transactions
Full API functionality

All test data can be safely created, modified, and deleted without affecting production.

Omise Documentation

API Reference - Complete Omise API documentation
Authentication Guide - API key management
Error Handling - Common errors and solutions
Testing Guide - Testing strategies and tools

MCP Resources

MCP Specification - Official MCP standard
MCP GitHub Repository - Open source implementation
Anthropic MCP Announcement - Introduction to MCP

Client Documentation

Claude Desktop - Download and setup guide
Continue Documentation - VS Code extension docs
Cline Documentation - Cline setup guide

Community

Omise Developer Community - Ask questions and share experiences
MCP Community Discord - MCP developer discussions
GitHub Discussions - Feature requests and feedback

Next Steps

Getting Started

Install MCP Server
```
npm install -g @omise/mcp-server
```
Configure Claude Desktop

Add Omise MCP server to your configuration
Test Connection

Ask Claude to retrieve your account balance
Explore Capabilities

Try different prompts and operations

Advanced Usage

Automate Workflows - Create complex multi-step operations
Build Custom Prompts - Develop prompt templates for common tasks
Integrate with CI/CD - Use MCP for automated testing
Team Training - Share best practices with your team

Need Help?

Support Email: support@omise.co
Documentation: docs.omise.co
Status Page: status.omise.co
Community Forum: community.omise.co

Ready to integrate Omise with AI? Install the MCP server and start automating your payment operations today!

Overview​

What is Model Context Protocol (MCP)?​

Key Benefits​

Installation​

Prerequisites​

Installing via npm​

Using with npx​

Verifying Installation​

Configuration​

Claude Desktop Setup​

Continue (VS Code Extension) Setup​

Cline Setup​

Environment Variables​

Available Tools​

Charge Operations​

Customer Operations​

Card Operations​

Refund Operations​

Transfer Operations​

Source Operations​

Balance Operations​

Dispute Operations​

Event Operations​

Usage Examples​

Example Prompts​

Conversation Flow Example​

Code Integration Example​

Configuration Options​

Advanced Server Configuration​

Configuration Parameters​

Multiple Environment Support​

Real-World Use Cases​

Customer Support Automation​

Financial Reconciliation​

Payment Investigation​

Subscription Management​

Development and Testing​

Security Considerations​

API Key Storage​

Securing Configuration Files​

Using Environment Variables​

Production Considerations​

Authentication Setup​

Obtaining API Keys​

Testing Authentication​

Troubleshooting Authentication​

Best Practices​

Development Workflow​

Prompt Engineering​

Data Management​

Production Usage​

Troubleshooting​

Common Issues​

MCP Server Not Loading​

Authentication Failures​

Tool Execution Failures​

Performance Issues​

Debug Mode​

Getting Help​

FAQ​

General Questions​

Technical Questions​

Related Resources​

Omise Documentation​

MCP Resources​

Client Documentation​

Community​

Next Steps​

Getting Started​

Advanced Usage​

Further Reading​

Need Help?​

Overview

What is Model Context Protocol (MCP)?

Key Benefits

Installation

Prerequisites

Installing via npm

Using with npx

Verifying Installation

Configuration

Claude Desktop Setup

Continue (VS Code Extension) Setup

Cline Setup

Environment Variables

Available Tools

Charge Operations

Customer Operations

Card Operations

Refund Operations

Transfer Operations

Source Operations

Balance Operations

Dispute Operations

Event Operations

Usage Examples

Example Prompts

Conversation Flow Example

Code Integration Example

Configuration Options

Advanced Server Configuration

Configuration Parameters

Multiple Environment Support

Real-World Use Cases

Customer Support Automation

Financial Reconciliation

Payment Investigation

Subscription Management

Development and Testing

Security Considerations

API Key Storage

Securing Configuration Files

Using Environment Variables

Production Considerations

Authentication Setup

Obtaining API Keys

Testing Authentication

Troubleshooting Authentication

Best Practices

Development Workflow

Prompt Engineering

Data Management

Production Usage

Troubleshooting

Common Issues

MCP Server Not Loading

Authentication Failures

Tool Execution Failures

Performance Issues

Debug Mode

Getting Help

FAQ

General Questions

Technical Questions

Related Resources

Omise Documentation

MCP Resources

Client Documentation

Community

Next Steps

Getting Started

Advanced Usage

Further Reading

Need Help?