OwnPay MCP Server - Connect AI Tools to Live Documentation

The OwnPay documentation hosts a public Model Context Protocol (MCP) server that lets AI assistants and coding agents search and retrieve content directly from the live documentation. Instead of relying on static training data or general web searches, your AI tools get accurate, real-time specifications from the actual docs.

The MCP server is available at https://ownpay.org/docs/mcp. It is read-only, publicly accessible, and requires no authentication.

1. What is MCP?

The Model Context Protocol is an open standard designed to connect AI applications to external data sources. When you connect your local AI development tool to the OwnPay MCP server, it gains three specific tools:

Search: Searches across all OwnPay documentation pages, returning relevant snippets and links.
Query docs filesystem: Reads and navigates pages using shell-style commands for batch reads.
Submit feedback: Reports outdated or incorrect information directly back to the OwnPay documentation team.

2. Connect Your AI Tool

Follow these steps to add the OwnPay MCP server to your preferred environment:

Cursor
Claude Desktop
Windsurf
VS Code (Cline/Roo Code)
Claude Code

To connect the OwnPay MCP server to Cursor:

Open MCP Settings

Open Cursor’s settings.
Navigate to Features > MCP.
Click + Add New MCP Server.

Configure the Server

Enter the following details in the dialog:

Name: ownpay-docs
Type: sse
URL: https://ownpay.org/docs/mcp

Verify Connection

In Cursor’s chat pane, ask: “What tools do you have available?” It should list ownpay-docs with the search and query tools active.

To add the server to the Claude Desktop application:

Open Configuration File

Open your Claude Desktop configuration file:

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

Add the Server Config

Insert the following snippet inside the mcpServers object:

{
  "mcpServers": {
    "ownpay-docs": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://ownpay.org/docs/mcp"
      ]
    }
  }
}

Restart Claude

Relaunch Claude Desktop. You will see a small plug icon showing that ownpay-docs has connected successfully.

To connect the server to Windsurf’s Cascade assistant:

Open configuration file

Open the global Windsurf MCP configuration file at ~/.codeium/windsurf/mcp_config.json.

Add the Server Configuration

Insert the configuration block:

{
  "mcpServers": {
    "ownpay-docs": {
      "serverUrl": "https://ownpay.org/docs/mcp"
    }
  }
}

Restart Windsurf

Restart the editor to enable search indexing in Cascade.

If you are using VS Code with extensions like Cline or Roo Code:

Open settings

Navigate to the extension’s MCP configuration settings.

Add the HTTP/SSE entry

Add a new HTTP server entry mapping:

Name: ownpay-docs
Type: sse
URL: https://ownpay.org/docs/mcp

To add the server via the Claude Code command-line interface:

claude mcp add --transport http ownpay-docs https://ownpay.org/docs/mcp

Verify the addition using:

claude mcp list

3. System Prompt for AI Assistants

Copy and paste this system prompt into your custom GPT instructions, Claude Project, or Cursor system settings to instruct your AI on how to interact with OwnPay:

You are an expert developer assistant specialized in the OwnPay payment orchestration platform. You have access to the OwnPay documentation MCP server at "https://ownpay.org/docs/mcp".

When answering questions or generating code:
1. Architecture Overview:
   - OwnPay is a self-hosted, open-source payment gateway platform.
   - It supports multi-brand (multi-tenant) scoping, where each brand has isolated database parameters, gateways, ledger logs, and custom checkout domains.
   - Core database tables include: `op_brands`, `op_gateways`, `op_transactions`, `op_ledger_entries`, `op_plugins`, and `op_domains`.
   - Pluggable extension directories: `modules/gateways/` (payment adapters), `modules/addons/` (filters and actions), and `modules/themes/` (custom Twig-based checkouts).

2. API Specifications:
   - Root-level endpoints:
     - POST `/api/v1/payments` (Create payment session redirect)
     - GET `/api/v1/payments/{trx_id}` (Verify payment status)
     - POST `/api/v1/refunds` (Refund transaction amount)
   - Uses Bearer Token authentication: Authorization: Bearer op_live_...

3. Best Practices & Conventions:
   - Use PSR-12 coding style for all PHP code.
   - Always perform server-to-server validation for webhook events; never trust client-side parameters.
   - Implement timing-attack-safe checks using `hash_equals()` for HMAC comparisons.
   - Enforce a 5-minute replay-window timeout on webhook header timestamps.

If a question requires precise file paths, settings schemas, or hooks details, proactively call the ownpay-docs MCP server tools to search the live documentation.

4. Discovery and Specifications

The MCP server supports automatic discovery. Systems that implement automated client connections can query the configuration metadata at:

https://ownpay.org/docs/mcp/.well-known/mcp

Server Rate Limits

To maintain service stability, public endpoints enforce the following hourly request rates:

Scope	Limit
Per User IP	5,000 requests/hour
Search per Site	10,000 requests/hour
Query Docs Filesystem per Site	10,000 requests/hour

5. Example Queries

Once configured, test the AI’s integration with queries like:

“How do I register a custom webhook event filter?”
“Show me how to build a Twig template for a custom checkout theme”
“What is the payload layout for payment.transaction.completed? ”
“How does the immutable double-entry ledger track merchant settlements?”
“Create a cURL request to initiate a white-label checkout session”

OwnPay Skills - Downloadable skill templates for agents
Developer Quickstart - Get started with APIs
Plugin System Overview - Core hooks and hooks catalog

​1. What is MCP?

​2. Connect Your AI Tool

​3. System Prompt for AI Assistants

​4. Discovery and Specifications

​Server Rate Limits

​5. Example Queries

​Related Pages

1. What is MCP?

2. Connect Your AI Tool

3. System Prompt for AI Assistants

4. Discovery and Specifications

Server Rate Limits

5. Example Queries

Related Pages