> ## Documentation Index
> Fetch the complete documentation index at: https://ownpay.org/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> OwnPay is licensed under AGPL-3.0 and is completely free - no licensing fees.
> Production docs URL: https://ownpay.org/docs - append .md to any page URL for clean markdown.
> OwnPay requires PHP 8.3+, MySQL/MariaDB, and Redis.
> MCP server available at https://ownpay.org/docs/mcp for programmatic documentation queries.
> Use root-relative links (e.g. /quickstart) for internal navigation - do NOT include /docs prefix.
> Plugin development: consult /developer/plugin-types/ pages for correct interfaces and manifests.

# OwnPay MCP Server - Connect AI Tools to Live Documentation

> Connect AI tools like Claude, Cursor, and Windsurf to the OwnPay docs via the Model Context Protocol server for real-time content access.

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.

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

## 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:

1. **Search**: Searches across all OwnPay documentation pages, returning relevant snippets and links.
2. **Query docs filesystem**: Reads and navigates pages using shell-style commands for batch reads.
3. **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:

<Tabs>
  <Tab title="Cursor">
    To connect the OwnPay MCP server to Cursor:

    <Steps>
      <Step title="Open MCP Settings">
        1. Open Cursor's settings.
        2. Navigate to **Features** > **MCP**.
        3. Click **+ Add New MCP Server**.
      </Step>

      <Step title="Configure the Server">
        Enter the following details in the dialog:

        * **Name:** `ownpay-docs`
        * **Type:** `sse`
        * **URL:** `https://ownpay.org/docs/mcp`
      </Step>

      <Step title="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.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Claude Desktop">
    To add the server to the Claude Desktop application:

    <Steps>
      <Step title="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`
      </Step>

      <Step title="Add the Server Config">
        Insert the following snippet inside the `mcpServers` object:

        ```json theme={null}
        {
          "mcpServers": {
            "ownpay-docs": {
              "command": "npx",
              "args": [
                "-y",
                "@modelcontextprotocol/server-sse",
                "https://ownpay.org/docs/mcp"
              ]
            }
          }
        }
        ```
      </Step>

      <Step title="Restart Claude">
        Relaunch Claude Desktop. You will see a small plug icon showing that `ownpay-docs` has connected successfully.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Windsurf">
    To connect the server to Windsurf's Cascade assistant:

    <Steps>
      <Step title="Open configuration file">
        Open the global Windsurf MCP configuration file at `~/.codeium/windsurf/mcp_config.json`.
      </Step>

      <Step title="Add the Server Configuration">
        Insert the configuration block:

        ```json theme={null}
        {
          "mcpServers": {
            "ownpay-docs": {
              "serverUrl": "https://ownpay.org/docs/mcp"
            }
          }
        }
        ```
      </Step>

      <Step title="Restart Windsurf">
        Restart the editor to enable search indexing in Cascade.
      </Step>
    </Steps>
  </Tab>

  <Tab title="VS Code (Cline/Roo Code)">
    If you are using VS Code with extensions like Cline or Roo Code:

    <Steps>
      <Step title="Open settings">
        Navigate to the extension's MCP configuration settings.
      </Step>

      <Step title="Add the HTTP/SSE entry">
        Add a new HTTP server entry mapping:

        * **Name:** `ownpay-docs`
        * **Type:** `sse`
        * **URL:** `https://ownpay.org/docs/mcp`
      </Step>
    </Steps>
  </Tab>

  <Tab title="Claude Code">
    To add the server via the Claude Code command-line interface:

    ```bash theme={null}
    claude mcp add --transport http ownpay-docs https://ownpay.org/docs/mcp
    ```

    Verify the addition using:

    ```bash theme={null}
    claude mcp list
    ```
  </Tab>
</Tabs>

***

## 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:

```text theme={null}
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:

```text theme={null}
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"*

***

## Related Pages

* [OwnPay Skills](/developer/ai-skills) - Downloadable skill templates for agents
* [Developer Quickstart](/developer/quickstart) - Get started with APIs
* [Plugin System Overview](/developer/plugins/overview) - Core hooks and hooks catalog


## Related topics

- [AI Tools Overview - Use AI Agents for Payment Development](/docs/developer/ai-overview.md)
- [OwnPay Skills for AI Agents - Platform Knowledge Pack](/docs/developer/ai-skills.md)
- [Addon Plugin AI Prompt - Generate Addon Extensions with AI](/docs/developer/plugin-types/addon-prompt.md)
- [Gateway Plugin AI Prompt: Generate Gateway Code with AI](/docs/developer/plugin-types/gateway-prompt.md)
- [Theme Plugin AI Prompt - Generate Checkout Themes with AI](/docs/developer/plugin-types/theme-prompt.md)