Referencia: Herramientas y Recursos MCP

Esta referencia técnica describe los endpoints, esquemas de entrada/salida de herramientas (Tools) y recursos de contexto (Resources) expuestos por el Servidor MCP Oficial de Parrot CRM (https://mcp.parrot.software/mcp).

---

Endpoints del Servidor

Endpoint	Método	Descripción	Autenticación
/mcp	POST / GET	Endpoint principal de Model Context Protocol (soporta JSON-RPC 2.0 y SSE)	Bearer Token
/.well-known/oauth-authorization-server	GET	Metadatos de descubrimiento OAuth 2.1 (RFC 8414)	Pública
/authorize	GET / POST	Interfaz web de autorización, login y selección de workspace	Web / Cookie
/oauth/token	POST	Intercambio de código de autorización por token de acceso	HTTP Basic / Client Auth
/oauth/register	POST	Dynamic Client Registration (RFC 7591)	Pública

Scopes requeridos

• crm:read: Permite invocar herramientas de consulta (read_crm, whoami, now) y leer recursos.
• crm:write: Permite invocar herramientas de modificación (write_crm).

---

Herramientas de Sistema

whoami

Retorna información sobre el usuario autenticado, el espacio de trabajo activo y su rol de permisos.

• Entrada: Sin parámetros.
• Salida:

{
  "username": "[email protected]",
  "parrotId": "mi-empresa",
  "role": "owner",
  "authenticated": true
}

now

Retorna la fecha y hora actual en tiempo universal coordinado (UTC) en formato ISO 8601. Esencial para que los LLMs interpreten expresiones temporales relativas.

• Entrada: Sin parámetros.
• Salida:

{
  "utc": "2026-10-08T19:30:00.000Z",
  "timestamp": 1791509400000
}

---

Herramienta de Lectura: read_crm

Unifica todas las operaciones de consulta segura en el CRM. Utiliza una unión discriminada por el campo action.

Acción 1: search

Busca registros mediante el motor de búsqueda indexada de CouchDB / Lucene.

{
  "action": "search",
  "query": "Carlos Slim",
  "limit": 10,
  "sort": "recent"
}

• Parámetros:
  • query (string, requerido): Texto de búsqueda (nombre, email, teléfono, contenido de mensaje).
  • limit (number, opcional, por defecto 10): Cantidad máxima de registros (máx 50).
  • sort (string, opcional): Ordenamiento (recent, score).

Acción 2: get

Recupera un documento específico por su ID o tipo de entidad.

{
  "action": "get",
  "id": "client:01HZX879ABCD...",
  "entity": "client"
}

• Parámetros:
  • id (string, requerido): Identificador único del documento o entidad.
  • entity (string, opcional): Tipo de entidad (client, thread, sale, knowledge).

Acción 3: timeline

Extrae la secuencia cronológica de mensajes, eventos y notas de un cliente o hilo omnicanal.

{
  "action": "timeline",
  "threadId": "thread:01HZX8...",
  "limit": 30
}

• Parámetros:
  • threadId o clientId (string): Identificador del hilo o del cliente a inspeccionar.
  • limit (number, opcional, por defecto 20): Límite de mensajes históricos a recuperar.

---

Herramienta de Escritura: write_crm

Unifica las operaciones de creación y actualización de registros comerciales. Utiliza una unión discriminada por el campo action.

1. create_client

Da de alta un nuevo cliente o contacto comercial.

{
  "action": "create_client",
  "name": "María González",
  "phone": "+525512345678",
  "email": "[email protected]",
  "tags": ["prospecto", "web"]
}

2. update_client

Modifica campos de un cliente existente.

{
  "action": "update_client",
  "clientId": "client:01HZX8...",
  "fields": {
    "empresa": "Soluciones SA",
    "presupuesto_estimado": 15000
  }
}

3. create_lead

Registra una oportunidad de venta asociada a un contacto.

{
  "action": "create_lead",
  "clientId": "client:01HZX8...",
  "title": "Licencias anuales",
  "amount": 24000,
  "pipelineStage": "nuevo"
}

4. update_pipeline_stage

Mueve un prospecto a una nueva fase dentro del embudo de ventas (Kanban).

{
  "action": "update_pipeline_stage",
  "leadId": "sale:01HZX8...",
  "stage": "cotizacion_enviada"
}

5. add_note

Añade una nota interna de seguimiento al perfil o hilo de un cliente.

{
  "action": "add_note",
  "clientId": "client:01HZX8...",
  "text": "Cliente interesado en plan Enterprise con facturación trimestral."
}

6. create_activity

Agenda una llamada, reunión o tarea pendiente para un miembro del equipo.

{
  "action": "create_activity",
  "clientId": "client:01HZX8...",
  "type": "call",
  "title": "Llamada de demostración",
  "dueDate": "2026-10-10T16:00:00Z"
}

7. add_faq / update_faq / delete_faq

Gestiona el catálogo de preguntas frecuentes utilizado tanto por respuestas automáticas como por asistentes de IA.

{
  "action": "add_faq",
  "question": "¿Cuáles son sus métodos de pago aceptados?",
  "answer": "Aceptamos transferencia bancaria, tarjetas de crédito (Visa/Mastercard) y Stripe."
}

---

Recursos de Contexto (Resources)

Los recursos MCP permiten que los modelos lean fragmentos estructurados de documentación o bases de conocimiento directamente en su memoria de contexto.

URI	Nombre	MIME Type	Descripción
parrot://knowledge/business	Perfil del Negocio y Políticas	text/markdown	Información general, horarios de atención, métodos de envío, políticas de garantía y devolución.
parrot://knowledge/faqs	Preguntas Frecuentes	text/markdown	Catálogo completo de preguntas y respuestas oficiales configuradas en el CRM.
parrot://knowledge/overview	Resumen Consolidado	text/markdown	Documento unificado con el perfil comercial y todas las FAQs activas.

Lectura de recursos en clientes MCP

La mayoría de los clientes MCP (como Claude Desktop o Cursor) pueden solicitar recursos de contexto explícitamente o incluirlos automáticamente como contexto del sistema al inicio de la sesión.