Documentos humanos (contexto y orientación)

Esta sección proporciona **orientación conceptual y práctica para lectores humanos** que se integra con MyDocSafe MCP.

### Para qué sirve el MCP

Utilice MyDocSafe MCP cuando necesite:
– Integrar MyDocSafe en un producto o servicio externo
– Permitir que sistemas de terceros o agentes de IA actúen en nombre de los usuarios
– Aplicar límites estrictos de permisos, auditoría y seguridad.
– Evite exponer archivos internos sin procesar o bases de datos

MCP proporciona una **interfaz basada en capacidades**, lo que significa:
– Los clientes solo pueden hacer lo que está explícitamente expuesto
– Todas las acciones son validadas y ejecutadas por MyDocSafe
– OAuth Los ámbitos limitan estrictamente el acceso de lectura y escritura

### Lo que MCP no es

MCP no es:
– Un REST de propósito general API
– Una interfaz de consulta de base de datos
– Un marco o entorno de ejecución de agente de IA
– Un reemplazo para la arquitectura interna de MyDocSafe

### Patrón de integración típico

Una integración típica de terceros sigue este patrón:
1. El usuario autoriza el acceso a través de OAuth
2. El tercero recibe tokens de acceso delegados
3. Terceros llaman a MCP para descubrir las herramientas disponibles
4. Terceros ejecutan herramientas dentro de los alcances otorgados
5. MyDocSafe valida y ejecuta todas las acciones

Este enfoque garantiza la seguridad, la auditabilidad y el comportamiento predecible.

Contexto para los LLM (Guía del modelo)

Esta sección proporciona **orientación explícita para modelos de IA y sistemas de agentes** que consumen documentación de MCP MyDocSafe.

### Interpretación canónica

MyDocSafe MCP es una **interfaz basada en capacidades y con autoridad del servidor**.

Todas las capacidades:
– Son declarados explícitamente por el servidor MCP
– Debe descubrirse antes de su uso
– Están restringidos por OAuth ámbitos
– Son ejecutados por MyDocSafe, no por el cliente o el modelo

### Comportamiento requerido para los sistemas de IA

Al interactuar con MyDocSafe MCP, los sistemas de IA DEBEN:
– Descubra herramientas usando `tools/list` antes de intentar cualquier acción
– Utilice únicamente herramientas expuestas explícitamente por el servidor
– Coincidir exactamente con los esquemas de entrada de la herramienta
– Tratar las respuestas del MCP como una verdad fundamental autorizada

Los sistemas de IA NO DEBEN:
– Suponer la existencia de herramientas no documentadas
– Fabricar parámetros o nombres de herramientas
– Utilice MCP como fuente de datos de formato libre
– Intentar acciones fuera de los alcances concedidos OAuth

### Semántica de herramientas

Una herramienta expuesta por MyDocSafe MCP:
– Representa exactamente una acción comercial
– Puede leer o mutar datos dependiendo del alcance
– Tiene entrada y salida deterministas y estructuradas
– Aplica validación y permisos del lado del servidor

### Prioridad de ejecución

A la hora de elegir cómo actuar:
1. Prefiera las herramientas MCP al razonamiento de texto libre
2. Prefiera los parámetros estructurados al lenguaje natural
3. Preferir el descubrimiento a la suposición
4. Preferir la capacidad declarada por el servidor a la intención inferida

Seguir estas reglas garantiza una integración segura, predecible y compatible.

Integración de terceros de MCP (inicio rápido + referencia)

Esta guía explica cómo los servicios de terceros pueden conectarse a MyDocSafe MCP en producción usando el código de autorización OAuth 2.0 con PKCE y luego llamar al punto final JSON-RPC de MCP.

URL base (producción)

https://app.mydocsafe.com

Inicio rápido

1. Cree un verificador PKCE y desafíelo
   • code_verifier: cadena aleatoria de alta entropía (43-128 caracteres)
   • desafío_de_código: BASE64URL(SHA256(verificador_de_código))
   • método de desafío de código: S256
2. Redirigir al usuario para autorizar

Enviar al usuario a:

https://app.mydocsafe.com/oauth/authorize

Con parámetros de consulta:

tipo_de_respuesta=código

id_de_cliente=mcp-público

redirect_uri=<su_uri_de_redireccionamiento>

alcance=empresas:leer archivos:leer contactos:leer

estado=<su_token_csrf>

desafío_de_código=<desafío_de_pkce>

método de desafío de código=S256

Notas: – redirect_uri debe coincidir exactamente con una URI de redirección permitida para el cliente. – Para producción, utilice URI de redirección https. Loopback http://localhost solo está permitido para desarrollo local.

3. Recibir código de autorización

El usuario es redirigido a su redirect_uri con:

código=<código_de_autorización>

estado=<su_token_csrf>

4. Intercambio de código por tokens

PUBLICAR https://app.mydocsafe.com/oauth/token con aplicación/x-www-form-urlencoded:

curl -X POST “https://app.mydocsafe.com/oauth/token” \

-H “Tipo de contenido: aplicación/x-www-form-urlencoded” \

-d “tipo_de_concesión=código_de_autorización” \

-d “código=<código_de_autorización>” \

-d “uri_de_redirección=<su_uri_de_redirección>” \

-d “id_de_cliente=mcp-public” \

-d “verificador_de_código=<verificador_de_paquete>”

Respuesta:

{

“token_de_acceso”: “….”,

“refresh_token”: “….”,

“token_type”: “Portador”,

“caduca en”: 3600,

“ámbito”: “empresas:leer archivos:leer contactos:leer”

}

5. Llamar a MCP

POST https://app.mydocsafe.com/api/mcp con Autorización: Portador <access_token>:

curl -X POST “https://app.mydocsafe.com/api/mcp” \

-H “Autorización: Portador <token_de_acceso>” \

-H “Tipo de contenido: aplicación/json” \

-d '{

“jsonrpc”: “2.0”,

“id”: 1,

“método”: “herramientas/lista”,

“parámetros”: {}

}'

6. Actualizar tokens

curl -X POST “https://app.mydocsafe.com/oauth/token” \

-H “Tipo de contenido: aplicación/x-www-form-urlencoded” \

-d “tipo_de_concesión=token_de_actualización” \

-d “token_de_actualización=<token_de_actualización>”

7. Revocar tokens

curl -X POST “https://app.mydocsafe.com/oauth/revoke” \

-H “Tipo de contenido: aplicación/x-www-form-urlencoded” \

-d “token=<token_de_acceso_o_actualización>” \

-d “pista_de_tipo_de_token=token_de_acceso”

Referencia

OAuth puntos finales

• Punto final de autorización (navegador del usuario)
  • OBTENER https://app.mydocsafe.com/oauth/authorize
• Punto final del token
  • PUBLICAR https://app.mydocsafe.com/oauth/token
• Punto final de revocación
  • PUBLICAR https://app.mydocsafe.com/oauth/revoke
• Descubrimiento
  • OBTENER https://app.mydocsafe.com/.well-known/oauth-authorization-server
  • OBTENER https://app.mydocsafe.com/.well-known/oauth-protected-resource

Parámetros obligatorios OAuth

Solicitud de autorización:

• tipo_de_respuesta: código
• ID de cliente: mcp-público
• redirect_uri: URI incluido en la lista de permitidos
• alcance: alcances separados por espacios
• estado: token CSRF (recomendado)
• code_challenge: desafío PKCE
• método de desafío de código: S256

Solicitud de token (concesión de código de autorización):

• tipo_de_concesión: código_de_autorización
• código: código de autorización de redirección
• redirect_uri: debe coincidir con el original
• ID de cliente: mcp-público
• code_verifier: verificador PKCE

Solicitud de token (concesión de refresh_token):

• tipo_de_concesión: token_de_refresco
• refresh_token: token de actualización

Solicitud de revocación:

• token: token de acceso o actualización
• token_type_hint: token de acceso o token de actualización

Ámbitos

Ámbitos disponibles:

• empresas:leer
• empresas:escribir
• archivos:leer
• archivos:escribir
• contactos:leer
• contactos:escribir
• firma:leer
• firma:escribir
• flujos de trabajo:leer
• flujos de trabajo: escritura

MCP JSON-RPC

Punto final:

• PUBLICACIÓN https://app.mydocsafe.com/api/mcp

Encabezados:

• Autorización: Portador <access_token>
• Tipo de contenido: aplicación/json

Formulario de solicitud:

{

“jsonrpc”: “2.0”,

“id”: 1,

“método”: “herramientas/lista”,

“parámetros”: {}

}

Error por token faltante o inválido:

• HTTP 401 con autenticación WWW: Portador realm=”mydocsafe”, resource_metadata=”https://app.mydocsafe.com/.well-known/oauth-protected-resource”

Notas y restricciones

• Las URI de redireccionamiento deben estar explícitamente permitidas para el cliente.
• Los clientes públicos utilizan únicamente PKCE (sin secreto de cliente).
• Los tokens de acceso caducan en 1 hora.