Conecta tu agente al servidor MCP de Stripe (mcp.stripe.com): OAuth, las 14 herramientas y una configuración segura

¿Cómo conecto mi agente al servidor MCP de Stripe?

Apunta un cliente MCP a https://mcp.stripe.com y autentícate con OAuth (recomendado, más seguro — permisos granulares y autorización por usuario) o con una llave restringida como Bearer token (Authorization: Bearer rk_...) para agentes autónomos. El servidor hospedado expone ~14 herramientas primarias — payment links, facturas, reembolsos, búsqueda de recursos — para que tu agente actúe en Stripe sin que escribas el código de las tools. En una sola línea con Claude Code queda conectado, y el resto de este post es dónde poner los límites para que un agente manipulado no pueda mover dinero que no debía.

Qué es el servidor MCP de Stripe (y hospedado vs. el Agent Toolkit embebido)

Stripe te da dos caminos soportados para que un agente actúe sobre tu propia cuenta, y conviene tenerlos separados desde el principio:

• El Stripe Agent Toolkit: una librería que embebes en tu propio agente. Vive en npm como @stripe/agent-toolkit (Node 18+) y en PyPI como stripe-agent-toolkit. Se integra con OpenAI Agents SDK, LangChain, CrewAI y Vercel AI SDK vía function calling. Tú decides en código exactamente qué acciones expones.
• El servidor MCP hospedado: un servidor remoto en https://mcp.stripe.com al que conecta tu cliente MCP. No instalas nada; te autenticas y las herramientas aparecen.

Ambos caminos están cerrados por la misma primitiva de seguridad: una Restricted API Key (RAK). Este post es el compañero del Agent Toolkit embebido; aquí nos enfocamos en el servidor hospedado. La diferencia mental: con el toolkit, el código de las tools corre en tu proceso; con el servidor MCP, Stripe hospeda las tools y tu agente solo las invoca por HTTP. Si nunca has conectado un agente a herramientas remotas, primero pasa por conectar un agente de IA a tus datos con MCP.

Las ~14 herramientas que expone — y por qué debes revisar los docs, no esta lista

El servidor hospedado expone alrededor de 14 herramientas primarias (que cubren unos 40+ métodos de la API). Algunas de las que verás: stripe_api_search, stripe_api_read, stripe_api_write, create_refund, search_stripe_resources y stripe_report. Los métodos soportados cubren crear y listar clientes, payment links, facturas, reembolsos y suscripciones.

Ahora la advertencia honesta: ese conteo de 14 es correcto al 2026-07-06, pero cambia. Stripe agrega y renombra herramientas. Trátalo como “~14 tools” y confirma la lista vigente contra los docs de Stripe MCP antes de cablear tu agente a un nombre de tool específico. No hardcodees un nombre de herramienta en tu lógica de negocio esperando que sea eterno; descubre las tools disponibles al conectar y valida contra la documentación.

La lección de diseño: las herramientas de escritura (stripe_api_write, create_refund) son las que mueven dinero o estado. Esas son las que vas a querer poner detrás de una confirmación, sin importar qué tan cómodo sea que el agente las llame solo.

OAuth vs. Bearer token con llave restringida: cuál usar y por qué OAuth es más seguro

El servidor MCP hospedado acepta dos métodos de autenticación, y la elección importa más de lo que parece.

OAuth (el default y el recomendado). Según Stripe, OAuth es “más seguro que usar tu secret key porque permite permisos más granulares y autorización basada en usuario”. Para apps de cara al usuario — donde cada persona autoriza su propio acceso — OAuth es la respuesta correcta. El grant se acota, se puede revocar por usuario, y no andas repartiendo una credencial estática.

Restricted API Key como Bearer token. Para agentes autónomos que corren sin un humano autorizando cada sesión, pasas una llave restringida en el header: Authorization: Bearer rk_.... Aquí entra la primitiva de seguridad más importante de todo el flujo.

Una Restricted API Key (RAK) empieza con rk_ (rk_test_ o rk_live_). A diferencia de una secret key (sk_) que puede hacer cualquier cosa en tu cuenta, “una RAK solo puede hacer lo que le des permiso de hacer”: permisos granulares por recurso — read, write o none. Le das al agente un rk_ acotado exactamente a las acciones que necesita y nada más. La llave es el tope duro del radio de explosión, incluso si el agente es manipulado por prompt injection.

Agregar mcp.stripe.com a tu cliente: Claude Code, Cursor y VS Code

Con Claude Code es una sola línea. El transporte es HTTP y la URL es la del servidor hospedado:

claude mcp add --transport http stripe https://mcp.stripe.com/

Para Cursor o VS Code, agregas una entrada al bloque mcpServers (Cursor) o servers (VS Code) apuntando a la misma URL:

{
  "mcpServers": {
    "stripe": {
      "url": "https://mcp.stripe.com"
    }
  }
}

Si prefieres autenticar con la llave restringida en lugar de pasar por el flujo OAuth del navegador, agregas el header Bearer con tu rk_:

{
  "mcpServers": {
    "stripe": {
      "url": "https://mcp.stripe.com",
      "headers": {
        "Authorization": "Bearer rk_live_..."
      }
    }
  }
}

Regla de oro: ese rk_ nunca va hardcodeado en un archivo que se commitea. Léelo de una variable de entorno o de un gestor de secretos. Un rk_live_ filtrado en un repo es exactamente el tipo de incidente que la llave restringida buscaba evitar. Si necesitas repasar cómo se conecta un cliente a un servidor MCP en general, está en conectar tu agente a MCP.

Conectarlo a un loop de tool use de Claude (tool_choice, esquemas strict, bloques tool_use)

Cuando conectas el servidor MCP a un loop de agente propio con la API de Claude, las herramientas de Stripe se convierten en definiciones de tool que el modelo puede elegir invocar. Las tools se declaran en el parámetro tools con name, description e input_schema (JSON Schema); strict: true fuerza la validación del esquema, y el modelo emite bloques tool_use que tú ejecutas y devuelves.

El parámetro que de verdad importa para la seguridad es tool_choice. Puede ser auto (el modelo decide), any (obligado a usar alguna tool), tool (una tool específica) o none (deshabilita las tools). Ese none es tu palanca: si detectas que el input viene de una fuente no confiable, corres primero una pasada con tool_choice: "none" para que el modelo razone sin poder ejecutar nada.

# Interceptas el bloque tool_use antes de ejecutarlo en Stripe
for block in message.content:
    if block.type == "tool_use" and block.name in MONEY_MOVING_TOOLS:
        # create_refund, stripe_api_write: NO se ejecuta solo.
        # El agente PROPONE; un humano o una regla determinista confirma.
        require_human_approval(block)
    else:
        result = run_stripe_tool(block)  # solo lecturas / búsquedas

El modelo vigente es claude-opus-4-8. Para el patrón completo del loop de tool use — cómo devolver el tool_result y cerrar el ciclo — está cómo usar la API de Claude y el agente autónomo con Claude Sonnet 5. Si además quieres estructura garantizada en las respuestas, revisa structured outputs en producción.

La postura de seguridad: acota el grant, protege las tools que mueven dinero, registra cada llamada

Aquí está el contenido real. El resto es plomería; esto es lo que te salva de un chargeback. La arquitectura de seguridad tiene cinco capas, y ninguna es opcional en producción:

1. Acota el rk_ a privilegio mínimo. Permisos por recurso: read donde solo lees, write solo donde de verdad debe escribir, none en todo lo demás. La llave es tu tope duro.
2. Expón solo las acciones que el agente necesita. No conectes las 14 tools “por si acaso”. Menos superficie, menos radio de explosión.
3. Exige aprobación humana antes de acciones que mueven dinero — reembolsos, payouts. El agente propone; un humano o una regla determinista confirma. Nunca un create_refund autónomo.
4. Prefiere OAuth sobre un Bearer secret para apps de cara al usuario. Autorización por usuario, revocable.
5. Registra cada llamada que el agente inicia en Stripe. Sin logs no hay forense ni detección.

El punto que amarra todo: asume que el agente PUEDE ser engañado por prompt injection, y diseña para que lo peor que pueda hacer esté acotado por la llave más tus confirmaciones. Esto es distinto de los Shared Payment Tokens / ACP (donde el comprador paga al comercio, el flujo opuesto): aquí el agente actúa sobre tu propia cuenta de Stripe. Un agente que puede emitir un reembolso está a una inyección indirecta de un incidente. Para el checklist completo de blindaje del servidor, está cómo asegurar un servidor MCP; y si el agente lee correo o WhatsApp, asegurarlo contra inyección.

Cuándo el servidor MCP hospedado gana al Agent Toolkit embebido — y cuándo no

No es que uno sea mejor; sirven a situaciones distintas. Mi regla, marcada como opinión de ingeniero.

Usa el servidor MCP hospedado cuando tu cliente ya habla MCP — Claude Code, Cursor, VS Code — y quieres conectar en una línea sin mantener código de tools. Es ideal para exploración, tareas operativas internas y agentes donde el cliente MCP es de un proveedor y tú solo quieres darle acceso acotado a Stripe. OAuth por usuario lo hace limpio para apps multiusuario.

Usa el Agent Toolkit embebido cuando necesitas control fino sobre exactamente qué acciones se exponen en código (configuration.actions), corres en un framework que ya integra el toolkit (LangChain, CrewAI, OpenAI Agents SDK, Vercel AI SDK), o quieres el doble candado: las tools disponibles son la intersección de tu config actions con los permisos de la llave restringida que pasas como secretKey. Ese doble límite — config más rk_ — es más difícil de lograr con el servidor hospedado solo.

En ambos casos, el rk_ es el tope duro y la compuerta humana es innegociable para dinero. Cambia el transporte, no la disciplina. Si vas a construir tu propio servidor MCP para exponer tu backend con el mismo cuidado, está crear tu propio servidor MCP en Python, y para agentes de producción completos, construir agentes con el Claude Agent SDK.

En resumen

Conectar tu agente a https://mcp.stripe.com es una línea. Hacerlo de forma segura es el trabajo real: autentica con OAuth cuando puedas, acota el rk_ a privilegio mínimo, expón solo las herramientas que el agente necesita, pon un humano frente a cualquier reembolso o payout, y registra cada llamada. Confirma la lista de ~14 tools contra los docs de Stripe MCP porque cambia, y revisa cómo se define una llave restringida en los restricted API keys docs. Asume que el agente puede ser engañado y asegúrate de que lo peor que pueda hacer siga siendo pequeño. Más guías en el hub de agentes de IA.