> ## Documentation Index
> Fetch the complete documentation index at: https://yn-c9bb3266.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Remote MCP Server (Detailed)

> Connect AI agents and automation clients to Yuno over a hardened MCP proxy with IP binding, rate limits, and session controls.

The Remote Yuno MCP Server implements the Model Context Protocol (MCP) to provide secure, remote access to Yuno services. It acts as a hardened proxy so AI agents and automation clients can call Yuno APIs over MCP with enterprise‑grade security and session controls.

## Local vs Remote MCP — which to use

|                   | Local MCP                                                   | Remote MCP                                                                             |
| ----------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| **Where it runs** | Developer machine (CLI launch)                              | Hosted by Yuno                                                                         |
| **Auth**          | API keys in local env                                       | API keys sent as HTTP headers, IP-bound session                                        |
| **Session model** | Process lifetime                                            | 30 min idle / 6 h absolute, Redis-backed                                               |
| **Rate limit**    | Yuno API limits only                                        | 15 req/min per session **on top of** Yuno API limits                                   |
| **Best for**      | Solo dev, prototyping, Cursor/Claude Desktop on your laptop | Teams, shared agents, anything where rotating credentials per developer is impractical |
| **Setup doc**     | [Building AI Integrations](/ai/llm-mcp-integration)         | This page                                                                              |

## Key capabilities

### Security

* **API key auth**: Requires `YUNO_PUBLIC_API_KEY`, `YUNO_PRIVATE_SECRET_KEY`, and `YUNO_ACCOUNT_CODE`
* **IP validation**: Sessions are bound to the client IP that initiated them. Requests from a different IP within the same session are rejected.
* **Rate limiting**: 15 requests per minute per session
* **Session timeouts**: 30 minutes idle; 6 hours absolute

### Protocols

* Streamable HTTP transport for bidirectional communication
* JSON‑RPC 2.0 for standardized request/response

### Session management

* Automatic creation, refresh, and cleanup
* Scheduled cleanup every 5 minutes
* Redis backend for persistent session and rate‑limit storage

## When to use the remote server

Use the Remote MCP Server when you want centralized security, observability, and policy enforcement (IP binding, rate limits, TTLs), or when teams and tools should connect without distributing raw API credentials locally. For rapid prototyping on a developer machine, the [local MCP](/ai/llm-mcp-integration) (CLI‑launched) may be sufficient.

## Endpoints

| Environment | URL                             |
| ----------- | ------------------------------- |
| Production  | `https://mcp.prod.y.uno/mcp`    |
| Sandbox     | `https://mcp.sandbox.y.uno/mcp` |

Use the matching credentials for each environment — sandbox keys against the sandbox URL, production keys against the production URL.

## Connecting from MCP‑compatible clients

The Remote MCP Server exposes an HTTP transport endpoint. Configure your MCP client to connect to your provisioned URL and pass the required headers.

<Tabs>
  <Tab title="Claude Desktop / Cursor">
    Add to your client's MCP config:

    ```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
    {
      "mcpServers": {
        "Yuno": {
          "transport": "http",
          "url": "https://mcp.prod.y.uno/mcp",
          "headers": {
            "public-api-key": "<YOUR_PUBLIC_API_KEY>",
            "private-secret-key": "<YOUR_PRIVATE_SECRET_KEY>",
            "account-code": "<YOUR_ACCOUNT_CODE>"
          }
        }
      }
    }
    ```

    Restart the client. Yuno tools should appear in the agent's tool palette.
  </Tab>

  <Tab title="cURL probe">
    Send an `initialize` request to confirm credentials and reachability:

    ```bash theme={"theme":{"light":"github-dark","dark":"github-dark"}}
    curl -X POST https://mcp.prod.y.uno/mcp \
      -H "Content-Type: application/json" \
      -H "public-api-key: $YUNO_PUBLIC_API_KEY" \
      -H "private-secret-key: $YUNO_PRIVATE_SECRET_KEY" \
      -H "account-code: $YUNO_ACCOUNT_CODE" \
      -d '{
        "jsonrpc": "2.0",
        "id": 1,
        "method": "initialize",
        "params": {
          "protocolVersion": "2024-11-05",
          "capabilities": {},
          "clientInfo": { "name": "probe", "version": "0.0.1" }
        }
      }'
    ```

    A 200 response with `result.serverInfo` confirms the connection. A 401 means bad credentials; 403 means an IP-binding mismatch.
  </Tab>
</Tabs>

<Note>
  Your `PUBLIC_API_KEY`, `PRIVATE_SECRET_KEY`, and `ACCOUNT_CODE` can all be obtained from the [Yuno dashboard](https://dashboard.y.uno/).
</Note>

## Available tools

The Remote MCP Server exposes the same tool catalog as the local MCP — every Yuno API endpoint is mapped to a callable tool (customers, payments, payment methods, checkout sessions, payment links, subscriptions, recipients, installment plans, and more). For the full list, see the [tool catalog in Building AI Integrations](/ai/llm-mcp-integration#available-tools).

## Errors and troubleshooting

| HTTP status   | JSON‑RPC error               | Cause                                                                       | Fix                                                                                                                              |
| ------------- | ---------------------------- | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `401`         | `-32001 Unauthorized`        | Missing or invalid `public-api-key` / `private-secret-key` / `account-code` | Re-copy credentials from Dashboard. Confirm you're using the right env (sandbox vs prod)                                         |
| `403`         | `-32002 IP mismatch`         | Request came from a different IP than the one that opened the session       | Sessions are IP-bound. Re-initialize from the new IP, or run agents from a stable egress (NAT / VPN)                             |
| `429`         | `-32003 Rate limit exceeded` | More than 15 requests per minute on a single session                        | Back off and retry. Use `Retry-After` header. Open additional sessions only if your client legitimately needs higher concurrency |
| `408`         | `-32004 Session expired`     | Idle > 30 min or session lifetime > 6 h                                     | Re-initialize. MCP clients usually do this automatically on the next call                                                        |
| `502` / `504` | —                            | Upstream Yuno API timeout or transient outage                               | Check [status.y.uno](https://status.y.uno). Retry with exponential backoff                                                       |

## Operational notes

* **Logging**: Yuno logs the tool name, request timestamp, source IP, and account code per call. Request bodies are not retained beyond what the underlying API logs.
* **Concurrency**: 15 req/min per session. To run multiple agents in parallel, open multiple sessions (each gets its own quota).
* **Credential rotation**: Rotate via Dashboard → Settings → Developers (Credentials). Existing sessions continue with the prior credential until they expire; new sessions must use the new credential.

## Related information

* [Building AI Integrations with Yuno's LLMs and MCP](/ai/llm-mcp-integration) — local MCP setup and full tool catalog
* [LLM Agent Instructions](/ai/llm-mcp-integration) — canonical doc URLs and SDK vs Direct Flow ordering tuned for AI agents
* [Aida AI Agent](/ai/aida-agent) — Yuno's hosted dashboard agent (different product, same underlying APIs)