RK
RefundKit
GitHubGet Started

MCP Server Setup

MCP Server Setup

The RefundKit MCP server is bundled with the @refundkit/sdk package. It can run in two modes: stdio (for local/desktop use) and HTTP (for production deployments).

Installation

The MCP server is included in the SDK package:

npm install @refundkit/sdk

Or run it directly with npx without installing:

npx @refundkit/sdk

Environment Variables

The MCP server requires one environment variable and accepts an optional one:

| Variable | Required | Description | |----------|----------|-------------| | REFUNDKIT_API_KEY | Yes | Your RefundKit API key (rk_test_ or rk_live_ prefix) | | REFUNDKIT_BASE_URL | No | Override the API base URL (default: https://api.refundkit.dev) |

stdio Mode

In stdio mode, the MCP server runs as a child process. The AI framework launches the server binary and communicates via stdin/stdout using JSON-RPC messages. This is the standard mode for local development and desktop applications.

Running Directly

REFUNDKIT_API_KEY=rk_test_your_key_here npx @refundkit/sdk

The server starts and listens for MCP protocol messages on stdin. You will not see any output -- it communicates exclusively through the MCP protocol.

Programmatic Usage

You can also create an MCP server instance in your own code:

import { createMcpServer } from '@refundkit/sdk/mcp';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = createMcpServer(
  process.env.REFUNDKIT_API_KEY!,
  process.env.REFUNDKIT_BASE_URL, // optional
);

const transport = new StdioServerTransport();
await server.connect(transport);

This gives you full control over the server lifecycle, allowing you to embed it in your own application or add custom middleware.

HTTP Mode

For production deployments where agents connect over the network, you can wrap the MCP server with an HTTP/SSE transport:

import { createMcpServer } from '@refundkit/sdk/mcp';
import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
import express from 'express';

const app = express();
const server = createMcpServer(process.env.REFUNDKIT_API_KEY!);

app.get('/sse', async (req, res) => {
  const transport = new SSEServerTransport('/messages', res);
  await server.connect(transport);
});

app.post('/messages', async (req, res) => {
  // Handle incoming MCP messages
  await transport.handlePostMessage(req, res);
});

app.listen(3100, () => {
  console.log('RefundKit MCP server running on http://localhost:3100');
});

Verifying the Server

To verify the server is working, you can use the MCP Inspector:

npx @modelcontextprotocol/inspector npx @refundkit/sdk

This opens a web UI where you can see the available tools, test them interactively, and inspect the JSON-RPC messages.

Docker Deployment

For containerized deployments:

FROM node:22-slim
WORKDIR /app
RUN npm install @refundkit/sdk
ENV REFUNDKIT_API_KEY=your_key_here
CMD ["npx", "@refundkit/sdk"]

Build and run:

docker build -t refundkit-mcp .
docker run -e REFUNDKIT_API_KEY=rk_live_your_key refundkit-mcp

Next Steps