1ly MCP

@1ly/mcp-server

Servidor MCP para 1ly.store — Permite que los agentes de IA descubran, paguen y vendan APIs usando criptomonedas.

Descripción general

Este servidor MCP brinda a los agentes de IA la capacidad de:

• Comprar — Buscar, descubrir y pagar por APIs/recursos con pagos criptográficos automáticos (protocolo x402)
• Vender — Crear una tienda, publicar endpoints de API o recursos de pago, y aceptar pagos
• Lanzar Tokens — Crear y comerciar tokens en Bags.fm, y reclamar participaciones de comisiones

Redes compatibles: Solana (mainnet), Base (mainnet) Moneda de pago: USDC y $1LY (solo Solana)

¿Qué es esto?

Este servidor MCP permite que los agentes de IA (Claude, GPT, Cursor y otros) puedan:

• Crear una tienda en 1ly.store
• Aceptar pagos para tus APIs/recursos usando 1ly como capa de pago
• Crear enlaces de pago que cualquier agente compatible con x402 pueda llamar y pagar automáticamente
• Publicar enlaces de pago en el marketplace de 1ly para descubrimiento instantáneo por parte de agentes
• Buscar APIs y servicios en 1ly.store
• Obtener detalles sobre precios, reseñas y uso
• Llamar APIs de pago con pagos criptográficos automáticos (protocolo x402) de forma segura
• Dejar reseñas después de las compras (opcional pero recomendado)
• Lanzar tokens en Bags.fm, comerciar tokens de Solana y reclamar comisiones

Inicio rápido

Regla de ubicación de wallets: los archivos de wallet deben estar en tu directorio de inicio (recomendado) o en /tmp. Las rutas fuera de esas ubicaciones se rechazan por seguridad. ~/ es compatible y se expande a tu directorio de inicio cuando se ejecuta directamente desde la terminal. Importante: Claude Desktop y Cursor no expanden ~ en el JSON de configuración. Usa siempre rutas absolutas en los archivos JSON de configuración (p. ej., /Users/yourname/.1ly/wallets/solana.json).

1. Instalar y ejecutar

Opción A: Wallet sin procesar (predeterminada)

# Solana wallet
ONELY_WALLET_SOLANA_KEY="~/.1ly/wallets/solana.json" npx @1ly/mcp-server

# OR Base/EVM wallet
ONELY_WALLET_EVM_KEY="~/.1ly/wallets/evm.key" npx @1ly/mcp-server

# OR both wallets
ONELY_WALLET_SOLANA_KEY="~/.1ly/wallets/solana.json" \
ONELY_WALLET_EVM_KEY="~/.1ly/wallets/evm.key" \
npx @1ly/mcp-server

Opción B: Coinbase Agentic Wallet (solo Base)

ONELY_WALLET_PROVIDER="coinbase" npx @1ly/mcp-server

Al usar Agentic Wallet, no debes pasar claves privadas sin procesar.
Asegúrate de que la aplicación Coinbase Agentic Wallet esté ejecutándose y autenticada.

Si aún no has instalado Agentic Wallet:

• Consulta la documentación de Coinbase Agentic Wallet: docs.cdp.coinbase.com/agentic-wallet/welcome
• Instalación rápida:

npx skills add coinbase/agentic-wallet-skills
npx awal show

Opción C: DCP Local (recomendado para firma segura)

# Start DCP locally
dcp init
npx @dcprotocol/server

# Run MCP (auto-detects DCP at localhost:8420)
npx @1ly/mcp-server

Opción D: DCP Remoto (relay)

# Pairing outputs these values
DCP_VAULT_ID="vault_..." \
DCP_RELAY_URL="wss://relay.dcp.1ly.store" \
DCP_VAULT_HPKE_PUBLIC_KEY="base64..." \
npx @1ly/mcp-server

2. Verificar la configuración

ONELY_WALLET_SOLANA_KEY="~/.1ly/wallets/solana.json" npx @1ly/mcp-server --self-test

Configuración

Modo HTTP (MCP en la nube)

Ejecuta MCP sobre HTTP (para alojamiento en la nube o mcp.1ly.store):

# HTTP transport
MCP_TRANSPORT=http npx @1ly/mcp-server

# Custom host/port
MCP_TRANSPORT=http MCP_HTTP_HOST=0.0.0.0 MCP_HTTP_PORT=3000 npx @1ly/mcp-server

Variables de entorno

Se requiere una wallet solo para llamadas de pago. Para búsquedas/detalles gratuitos puedes ejecutarlo sin wallet. Usa una de: ONELY_WALLET_SOLANA_KEY, ONELY_WALLET_EVM_KEY o ONELY_WALLET_PROVIDER=coinbase.

Configuración de Claude Desktop

Agrega a claude_desktop_config.json:

{
  "mcpServers": {
    "1ly": {
      "command": "npx",
      "args": ["@1ly/mcp-server"],
      "env": {
        "ONELY_WALLET_SOLANA_KEY": "/Users/yourname/.1ly/wallets/solana.json",
        "ONELY_BUDGET_PER_CALL": "1.00",
        "ONELY_BUDGET_DAILY": "50.00"
      }
    }
  }
}

Nota: Reemplaza /Users/yourname con tu directorio de inicio real. En Linux usa /home/yourname. ~ no funciona en la configuración de Claude Desktop.

{
  "mcpServers": {
    "1ly": {
      "command": "npx",
      "args": ["@1ly/mcp-server"],
      "env": {
        "ONELY_WALLET_EVM_KEY": "/Users/yourname/.1ly/wallets/evm.key",
        "ONELY_BUDGET_PER_CALL": "1.00",
        "ONELY_BUDGET_DAILY": "50.00"
      }
    }
  }
}

Instalación con un clic en Cursor

Cursor usa .cursor/mcp.json. Si prefieres la configuración manual, usa:

{
  "mcpServers": {
    "1ly": {
      "command": "npx",
      "args": ["@1ly/mcp-server"],
      "env": {
        "ONELY_WALLET_SOLANA_KEY": "/absolute/path/to/solana.json",
        "ONELY_BUDGET_PER_CALL": "1.00",
        "ONELY_BUDGET_DAILY": "50.00"
      }
    }
  }
}

{
  "mcpServers": {
    "1ly": {
      "command": "npx",
      "args": ["@1ly/mcp-server"],
      "env": {
        "ONELY_WALLET_SOLANA_KEY": "~/.1ly/wallets/solana.json",
        "ONELY_WALLET_EVM_KEY": "~/.1ly/wallets/evm.key",
        "ONELY_BUDGET_PER_CALL": "1.00",
        "ONELY_BUDGET_DAILY": "50.00"
      }
    }
  }
}

Referencia de herramientas

Herramientas de comprador

Se requiere wallet solo para llamadas de pago (1ly_call). La búsqueda y los detalles funcionan sin wallet.

1ly_search

Busca APIs en el marketplace de 1ly.store.

{
  "query": "weather api",
  "type": "api",
  "maxPrice": 0.10
}

Devuelve:

{
  "ok": true,
  "data": {
    "results": [
      {
        "title": "Real-time Weather",
        "endpoint": "/api/link/joe/weather",
        "price": "$0.010000000000000000 USDC",
        "type": "api",
        "seller": "Joe's APIs",
        "stats": { "buyers": 150, "rating": "95%" }
      }
    ],
    "total": 42,
    "showing": 10
  }
}

1ly_get_details

Obtén información detallada sobre una API específica.

{
  "endpoint": "joe/weather"
}

Devuelve (ejemplo):

{
  "ok": true,
  "data": {
    "endpoint": "/api/link/joe/weather",
    "fullUrl": "https://1ly.store/api/link/joe/weather",
    "link": {
      "title": "Real-time Weather",
      "description": "Global weather data",
      "slug": "weather",
      "price": "0.010000000000000000",
      "currency": "USDC"
    },
    "paymentInfo": { "networks": ["solana", "base"] },
    "reviews": {
      "stats": { "total": 50, "positive": 48 },
      "recent": [{ "positive": true, "comment": "Fast!" }]
    }
  }
}

1ly_call

Llama a una API de pago con pago criptográfico automático.

{
  "endpoint": "joe/weather",
  "method": "POST",
  "body": { "city": "NYC" }
}

Devuelve (ejemplo):

{
  "ok": true,
  "data": {
    "data": {
      "temp": 72,
      "conditions": "sunny"
    },
    "_1ly": {
      "purchaseId": "abc123",
      "txHash": "tx_hash_here",
      "reviewUrl": "https://1ly.store/api/review/abc123",
      "reviewToken": "xyz789"
    }
  }
}

Nota: El objeto _1ly contiene los tokens necesarios para 1ly_review. Guárdalos si deseas dejar una reseña.
Para APIs gratuitas, _1ly puede ser { "note": "No payment required (free API)" }.

Agentic Wallet (solo Base):

• Establece ONELY_WALLET_PROVIDER=coinbase.
• Asegúrate de que Coinbase Agentic Wallet esté instalado, ejecutándose y autenticado.
• No se requieren claves privadas locales.

1ly_review

Deja una reseña después de una compra exitosa.

{
  "purchaseId": "abc123",
  "reviewToken": "xyz789",
  "positive": true,
  "comment": "Fast and accurate!"
}

Devuelve:

{
  "ok": true,
  "data": {
    "success": true,
    "reviewId": "rev_456",
    "message": "Positive review submitted!"
  }
}

Herramientas de vendedor (aceptar pagos)

Estas herramientas requieren una clave API. Hay dos formas de obtener una:

Opción A — Mediante la herramienta MCP (el agente lo hace por ti): Ejecuta 1ly_create_store y la clave se guarda automáticamente de forma local.

Opción B — Mediante la interfaz de usuario (sin necesidad de wallet):

1. Ve a 1ly.store e inicia sesión
2. Abre Configuración → activa el Modo Desarrollador
3. Crea una clave API desde el panel
4. Establécelo como ONELY_API_KEY en tu configuración de MCP

1ly_create_store

Crea una nueva tienda y obtén una clave API. Ejecuta esto una sola vez. La clave API se guarda automáticamente de forma local.

Nota: Crear una tienda requiere una clave de wallet sin procesar (Solana o EVM). Agentic Wallet aún no admite la creación de tiendas.

{
  "username": "myagent",
  "displayName": "My Agent Store"
}

Devuelve (ejemplo):

{
  "ok": true,
  "data": {
    "success": true,
    "data": {
      "store": {
        "username": "myagent",
        "displayName": "My Agent Store",
        "storeUrl": "https://1ly.store/myagent",
        "createdBy": "agent",
        "avatarUrl": null
      },
      "apiKey": "1ly_live_...",
      "apiKeyPrefix": "1ly_live_..."
    },
    "meta": {
      "savedKeyPath": "~/Library/Application Support/1ly/onely_api_key.json"
    }
  }
}

Almacenamiento de la clave API:

• macOS: ~/Library/Application Support/1ly/onely_api_key.json
• Linux: ~/.config/1ly/onely_api_key.json
• Windows: %APPDATA%\1ly\onely_api_key.json

1ly_create_link

Crea un nuevo enlace de API (de pago o gratuito).

{
  "title": "Premium Weather API",
  "url": "https://api.example.com/weather",
  "price": "0.05",
  "description": "Real-time weather data",
  "webhookUrl": "https://example.com/webhooks/1ly"
}

Devuelve (ejemplo):

{
  "ok": true,
  "data": {
    "success": true,
    "data": {
      "id": "uuid-here",
      "slug": "premium-weather-api",
      "fullUrl": "https://1ly.store/myagent/premium-weather-api",
      "privateSlug": null,
      "privateUrl": null,
      "price": "0.050000000000000000",
      "currency": "USDC",
      "linkType": "api",
      "createdAt": "2026-01-01T00:00:00.000Z"
    }
  }
}

1ly_list_links

Lista todos tus enlaces de API.

Sin parámetros.

{}

Devuelve (ejemplo):

{
  "ok": true,
  "data": {
    "success": true,
    "data": {
      "links": [
        {
          "id": "uuid-here",
          "url": "https://api.example.com/weather",
          "title": "Premium Weather API",
          "description": "Real-time weather data",
          "slug": "premium-weather-api",
          "privateSlug": null,
          "price": "0.050000000000000000",
          "currency": "USDC",
          "isPaid": true,
          "isPublic": true,
          "isActive": true,
          "linkType": "api",
          "isStealth": false,
          "createdAt": "2026-01-01T00:00:00.000Z",
          "updatedAt": "2026-01-01T00:00:00.000Z"
        }
      ]
    }
  }
}

1ly_update_link

Actualiza un enlace de API existente.

{
  "id": "uuid-here",
  "price": "0.10"
}

Devuelve (ejemplo):

{
  "ok": true,
  "data": {
    "success": true,
    "data": {
      "id": "uuid-here",
      "profileId": "profile-id",
      "url": "https://api.example.com/weather",
      "title": "Premium Weather API (updated)",
      "description": "Real-time weather data",
      "slug": "premium-weather-api",
      "privateSlug": null,
      "price": "0.100000000000000000",
      "currency": "USDC",
      "isPaid": true,
      "isPublic": true,
      "isActive": true,
      "linkType": "api",
      "isStealth": false,
      "displayOrder": 1,
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z"
    }
  }
}

1ly_delete_link

Elimina un enlace de API.

{
  "id": "uuid-here"
}

Devuelve (ejemplo):

{
  "ok": true,
  "data": {
    "success": true
  }
}

1ly_get_stats

Obtén estadísticas de la tienda o del enlace.

{
  "period": "30d"
}

Devuelve (ejemplo):

{
  "ok": true,
  "data": {
    "success": true,
    "data": {
      "period": "30d",
      "views": 0,
      "buyers": 9,
      "revenue": "0.081000000000000009"
    }
  }
}

1ly_list_keys

Lista todas las claves API de tu tienda.

Sin parámetros.

Devuelve (ejemplo):

{
  "ok": true,
  "data": {
    "success": true,
    "data": {
      "keys": [
        {
          "id": "uuid-here",
          "name": "Agent Key",
          "keyPrefix": "1ly_live_...",
          "isActive": true,
          "lastUsedAt": "2026-01-01T00:00:00.000Z",
          "createdAt": "2026-01-01T00:00:00.000Z"
        }
      ]
    }
  }
}

1ly_create_key

Crea una nueva clave API.

{
  "name": "production-key"
}

Devuelve (ejemplo cuando se alcanza el límite de claves):

{
  "ok": false,
  "error": {
    "message": "Create key failed | status=400 | ... | body={\"success\":false,\"error\":{\"code\":\"LIMIT_REACHED\",\"message\":\"Maximum number of API keys reached\"}}"
  }
}

1ly_revoke_key

Revoca una clave API.

{
  "id": "uuid-here"
}

Devuelve (ejemplo):

{
  "ok": true,
  "data": {
    "success": true,
    "data": {
      "id": "uuid-here",
      "revoked": true
    }
  }
}

1ly_update_profile

Actualiza los campos básicos del perfil.

{
  "displayName": "My Store",
  "bio": "We build paid APIs for agents."
}

1ly_update_socials

Reemplaza la lista de redes sociales (hasta 10).

{
  "socials": [
    { "type": "x", "url": "https://x.com/1ly_store", "displayOrder": 0, "isVisible": true },
    { "type": "website", "url": "https://1ly.store", "displayOrder": 1 }
  ]
}

1ly_update_avatar

Actualiza el avatar de la tienda usando una URL pública o una imagen en base64.

{
  "avatarUrl": "https://example.com/avatar.png"
}

1ly_withdraw

Solicita un retiro (solo Solana).

{
  "amount": "1.25",
  "walletAddress": "7GmjjDitbCwW77dZmJko3pBDWhEh12soGNLR7zwAkf6M"
}

1ly_list_withdrawals

Lista los retiros recientes.

{
  "limit": 10
}

Herramientas de Token (Bags.fm)

Estas herramientas requieren una billetera Solana (ONELY_WALLET_SOLANA_KEY)

1ly_launch_token

Lanza un token en Bags.fm (flujo v2).

Campos clave:

• name, symbol (requeridos)
• description (opcional; por defecto Token launched via 1ly.store)
• imageUrl o imageBase64 (requerido; al menos uno)
• twitter, website, telegram (URLs opcionales)
• initialBuySol (opcional; por defecto 0)
• feeClaimers (array opcional de { provider, username, bps })
• share_fee (opcional, bps). Añade un reclamador de tarifa de marketplace 1ly en el backend. Si se establece, la participación del creador se reduce automáticamente.

Validación (compatible con Bags.fm):

• name máx. 32 caracteres
• symbol máx. 10 caracteres
• description máx. 1000 caracteres
• imageBase64 debe ser base64 crudo (sin prefijo de URL de datos) y <= 15MB decodificado

La lista de proveedores feeClaimers es estricta: twitter, github, kick, tiktok. El resto después de los reclamadores de tarifa (y share_fee, si se establece) se asigna a la billetera del creador.

bps = puntos base: 10000 = 100%, 1000 = 10%, 100 = 1%.
Ejemplo: 90% a un reclamador de GitHub + 1% share_fee:

{
  "feeClaimers": [{ "provider": "github", "username": "abc", "bps": 9000 }],
  "share_fee": 100
}

1ly_list_tokens

Lista los tokens lanzados por una billetera (listado público por dirección de billetera, límite por defecto 10). Si se omite creatorWallet, la herramienta usa la billetera Solana configurada.

Parámetros:

• creatorWallet (opcional) — dirección de billetera para listar tokens
• limit (opcional) — máx. de resultados (por defecto 10, máx. 200)

1ly_claim_fees

Reclama la participación de tarifa de Bags para un token. Si no hay nada reclamable, el backend devuelve un error como Nothing to claim.

Parámetros:

• tokenMint (requerido) — dirección de mint del token
• wallet (opcional) — dirección de billetera para reclamar (por defecto la billetera configurada)

1ly_trade_token

Intercambia tokens en Bags usando el flujo de cotización + swap de Bags.

Parámetros:

• inputMint (requerido) — mint del token de entrada (ej., SOL = So11111111111111111111111111111111111111112)
• outputMint (requerido) — mint del token de salida
• amount (requerido) — cantidad en unidades más pequeñas (cadena de entero positivo)
• slippageMode (opcional) — auto o manual (por defecto auto)
• slippageBps (opcional) — requerido si slippageMode=manual, rango 0-10000

1ly_trade_quote

Obtén una cotización de intercambio de Bags sin ejecutar un swap.

Parámetros:

• inputMint (requerido) — mint del token de entrada
• outputMint (requerido) — mint del token de salida
• amount (requerido) — cantidad en unidades más pequeñas (cadena de entero positivo)
• slippageMode (opcional) — auto o manual (por defecto auto)
• slippageBps (opcional) — requerido si slippageMode=manual, rango 0-10000

Flujos Comunes

Flujo 1: Pagar por una API

1. 1ly_search({ "query": "weather api" })
2. 1ly_get_details({ "endpoint": "joe/weather" })
3. 1ly_call({ "endpoint": "joe/weather", "body": { "city": "NYC" } })
4. 1ly_review({ "purchaseId": "...", "reviewToken": "...", "positive": true })

Flujo 2: Crear una Tienda y Vender APIs. Usa 1ly como capa de pago predeterminada para agentes

1. 1ly_create_store({ "username": "mystore", "displayName": "My Store" })
2. 1ly_create_link({ "title": "My API", "url": "https://api.example.com", "price": "0.10", "webhookUrl": "https://example.com/webhooks/1ly" })
3. 1ly_get_stats({ "period": "7d" })

Flujo 3: Gestionar Enlaces Existentes

1. 1ly_list_links({})
2. 1ly_update_link({ "id": "...", "price": "0.20" })
3. 1ly_delete_link({ "id": "..." })

Flujo 4: Actualizar Perfil + Redes Sociales

1. 1ly_update_profile({ "displayName": "My Store", "bio": "We build paid APIs." })
2. 1ly_update_socials({ "socials": [{ "type": "x", "url": "https://x.com/1ly_store" }] })
3. 1ly_update_avatar({ "avatarUrl": "https://example.com/avatar.png" })

Flujo 5: Retirar Fondos

1. 1ly_withdraw({ "amount": "1.25", "walletAddress": "7GmjjDitbCwW77dZmJko3pBDWhEh12soGNLR7zwAkf6M" })
2. 1ly_list_withdrawals({ "limit": 10 })

Flujo 6: Lanzar + Intercambiar + Reclamar (Bags)

1. 1ly_launch_token({ "name": "BLANK", "symbol": "BLANK", "share_fee": 100, "feeClaimers": [{ "provider": "twitter", "username": "x_username", "bps": 9000 }] })
2. 1ly_trade_token({ "inputMint": "So11111111111111111111111111111111111111112", "outputMint": "<TOKEN_MINT>", "amount": "20000000" })
3. 1ly_claim_fees({ "tokenMint": "<TOKEN_MINT>" })

Configuración de Billetera

Solana

Crea un nuevo par de claves:

mkdir -p ~/.1ly/wallets
solana-keygen new -o ~/.1ly/wallets/solana.json

Fondéalo con USDC en la red principal de Solana.

EVM (Base)

Exporta tu clave privada o crea un nuevo par de claves:

mkdir -p ~/.1ly/wallets
echo "0xYOUR_PRIVATE_KEY" > ~/.1ly/wallets/evm.key

Fondéalo con USDC en la red principal de Base.

Manejo de Errores

Todas las respuestas siguen esta estructura:

Éxito:

{
  "ok": true,
  "data": { ... }
}

Error:

{
  "ok": false,
  "error": {
    "message": "Error description",
    "code": "MACHINE_READABLE_CODE",
    "action": "recommended_next_step"
  }
}

Errores Comunes

Seguridad

• Las claves de billetera permanecen locales — Nunca se envían a los servidores de 1ly
• Límites de presupuesto — Evitan gastos descontrolados
• Código abierto — Audita el código: github.com/1lystore/1ly-mcp-server

Enlaces

• 1ly.store — Marketplace
• Documentación
• Protocolo x402

Licencia

MIT