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	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 (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.

Claude Desktop / Cursor

Add to your client’s MCP config:

{
  "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.

cURL probe

Send an initialize request to confirm credentials and reachability:

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.

Your PUBLIC_API_KEY, PRIVATE_SECRET_KEY, and ACCOUNT_CODE can all be obtained from the Yuno dashboard.

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.

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. 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 — local MCP setup and full tool catalog
• LLM Agent Instructions — canonical doc URLs and SDK vs Direct Flow ordering tuned for AI agents
• Aida AI Agent — Yuno’s hosted dashboard agent (different product, same underlying APIs)