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

# OpenAPI MCP Server

> Connect to UniBee’s public MCP endpoint to search OpenAPI definitions, generate example requests, and read integration playbooks—documentation only, no business API proxy.

## Overview

UniBee exposes a **Model Context Protocol (MCP)** service over HTTPS so agents and integrators can **discover and understand** the UniBee OpenAPI surface. It helps you search endpoints, inspect schemas, generate example `curl` commands, and follow scenario playbooks.

| Item                    | Value                                        |
| ----------------------- | -------------------------------------------- |
| **Production endpoint** | `https://api.unibee.dev/mcp`                 |
| **Protocol**            | JSON-RPC 2.0                                 |
| **Purpose**             | OpenAPI documentation retrieval and examples |

This service is **documentation-only**. It does **not** execute UniBee business APIs on your behalf.

***

## Agent configuration

Add a **remote MCP server** in your agent or IDE and set the URL to:

```text theme={null}
https://api.unibee.dev/mcp
```

Example configuration (field names may differ by platform):

```json theme={null}
{
  "mcpServers": {
    "unibee-openapi": {
      "url": "https://api.unibee.dev/mcp"
    }
  }
}
```

If the platform requires an explicit transport:

```json theme={null}
{
  "mcpServers": {
    "unibee-openapi": {
      "url": "https://api.unibee.dev/mcp",
      "transport": "http"
    }
  }
}
```

***

## Service boundaries

* The MCP endpoint returns **OpenAPI metadata** (paths, parameters, schemas, example curls, integration hints). It does **not** substitute for calling UniBee production or sandbox APIs from your own systems.
* Tools such as `generate_example_request` output **example** HTTP requests you copy and run yourself after filling real credentials and business fields.
* You do **not** need Node.js or a local checkout of this docs repo to use the MCP server.

***

## Authentication

Connecting to the MCP server **does not** require a UniBee merchant **Bearer token**. The MCP layer is intended for public documentation access.

Keep two concepts separate:

| Concern                   | Behavior                                                                                                 |
| ------------------------- | -------------------------------------------------------------------------------------------------------- |
| **MCP connection**        | No business API token required to call `https://api.unibee.dev/mcp`.                                     |
| **Real UniBee API calls** | Use the authentication required by each business endpoint (typically `Authorization: Bearer <API_KEY>`). |

The optional `authToken` argument on `generate_example_request` is only used to **embed a token inside the generated example curl** for convenience. It is **not** the MCP server’s own auth parameter. If omitted, examples use a placeholder such as `Authorization: Bearer <YOUR_TOKEN>`.

***

## JSON-RPC methods

Supported methods:

* `initialize`
* `tools/list`
* `tools/call`

***

## Available tools

| Tool                       | Purpose                                            |
| -------------------------- | -------------------------------------------------- |
| `list_specs`               | List available OpenAPI document sources.           |
| `search_endpoints`         | Search endpoints by keyword, tag, or path prefix.  |
| `get_endpoint`             | Return full detail for one path + HTTP method.     |
| `generate_example_request` | Build an example curl for a given path and method. |
| `integration_playbook`     | Return step-by-step guidance for common scenarios. |

### `search_endpoints`

* `query` (optional): keyword across path, summary, description
* `tag` (optional): filter by OpenAPI tag
* `pathPrefix` (optional): filter by URL prefix
* `limit` (optional): default 20, max 100

### `get_endpoint`

* `path` (required), e.g. `/merchant/plan/list`
* `method` (required), e.g. `GET` or `POST`

### `generate_example_request`

* `path` (required)
* `method` (required)
* `authToken` (optional): inserted into the generated example `Authorization` header only

### `integration_playbook`

* `scenario` (required), one of:
  * `merchant_subscription`
  * `checkout_payment`
  * `system_refund`

***

## Example requests

### Initialize

```bash theme={null}
curl -X POST "https://api.unibee.dev/mcp" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"initialize",
    "params":{}
  }'
```

### List tools

```bash theme={null}
curl -X POST "https://api.unibee.dev/mcp" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":2,
    "method":"tools/list",
    "params":{}
  }'
```

### Call `search_endpoints`

```bash theme={null}
curl -X POST "https://api.unibee.dev/mcp" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":3,
    "method":"tools/call",
    "params":{
      "name":"search_endpoints",
      "arguments":{
        "query":"subscription",
        "limit":10
      }
    }
  }'
```

### Call `generate_example_request`

```bash theme={null}
curl -X POST "https://api.unibee.dev/mcp" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":4,
    "method":"tools/call",
    "params":{
      "name":"generate_example_request",
      "arguments":{
        "path":"/merchant/plan/list",
        "method":"GET"
      }
    }
  }'
```

The responses above come from the **MCP documentation service**. Any curl inside the tool output is an **example** for UniBee business APIs—you still run those requests from your own environment with real credentials and parameters.

***

## Recommended workflow

1. Call `integration_playbook` with your scenario.
2. Use `search_endpoints` to find relevant routes.
3. Use `get_endpoint` to read request/response schemas and security requirements.
4. Use `generate_example_request` to draft a curl, then add real auth and body fields.
5. Execute the business API from your own application or API client.

***

## Summary

UniBee’s **OpenAPI MCP** helps you **explore and document** the API faster; it does **not** replace authenticated calls to UniBee business endpoints from your systems.