Conectar un cliente de IA mediante MCP

Dureach expone un servidor MCP de lectura y acción en https://app.dureach.com/mcp para clientes MCP externos. El cliente completa el consentimiento OAuth, llama a tools/list para descubrir las herramientas concedidas y luego llama a tools/call con un nombre de herramienta dureach.* y argumentos tipados.

Los resultados se transfieren al cliente externo y su proveedor puede procesarlos o conservarlos. Revise sus condiciones de tratamiento, conservación y acceso a los datos antes de conectar. Solicite solo los campos necesarios; no incluya datos de contacto ni registros de clientes en conversaciones compartidas, capturas o registros.

¿Qué necesita antes de conectarse?

Un espacio de trabajo de Dureach con la capacidad de plataforma de agentes habilitada. Sin ella, la admisión devuelve plan_capability_required.
Un cliente OAuth que pueda completar una concesión de consentimiento en el navegador. MCP solo acepta tokens de portador OAuth; las claves de API REST se rechazan en /mcp.
Complete el consentimiento en el navegador como miembro del espacio de trabajo. Guarde las credenciales en el almacén protegido del cliente o en un gestor de secretos del servidor. Nunca pegue un token en una conversación, documento compartido, captura o ticket.
Un cliente MCP compatible con HTTP transmitible con respuestas JSON (por ejemplo, Claude Desktop con un conector MCP, Cursor o un cliente Python personalizado basado en el SDK mcp).

¿Cómo funciona el consentimiento OAuth para MCP?

Registre o abra su cliente OAuth e inicie una concesión de autorización para el espacio de trabajo.
Seleccione solo los ámbitos que el cliente necesita (consulte Aprobaciones, políticas y cuotas de MCP). Un cliente de informes puede necesitar solo companies:read y trade:read; un cliente de prospección necesita concesiones adicionales de leads:create o emails:send.
Complete el consentimiento en el navegador como miembro del espacio de trabajo. Guarde las credenciales en el almacén protegido del cliente o en un gestor de secretos del servidor. Nunca pegue un token en una conversación, documento compartido, captura o ticket.
Envíe el token como Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN en cada solicitud HTTP de MCP. Manténgalo fuera de URL, capturas de pantalla, registros e incidencias.
Si el cliente debe actuar para un espacio de trabajo específico, envíe X-Workspace-ID con el ID del espacio de trabajo del token. Un valor no coincidente devuelve workspace_context_required.

Consulte el documento de metadatos en /.well-known/oauth-protected-resource/mcp cuando su biblioteca cliente necesite valores de descubrimiento.

¿Qué endpoint y protocolo utiliza el cliente?

Use exactamente https://app.dureach.com/mcp con un cliente MCP compatible con streamable HTTP.
Complete el consentimiento OAuth para el espacio de trabajo previsto; guarde las credenciales en el almacén protegido del cliente o en un gestor de secretos del servidor.
Si se rechaza el host o el origen, verifique la URL configurada y contacte con soporte. No elimine ni falsifique cabeceras de seguridad para eludir el rechazo.
Conserve el request_id de la respuesta para diagnóstico; nunca incluya tokens ni filas de resultados en registros compartidos.

¿Cómo se listan las herramientas disponibles?

Tras el consentimiento OAuth, llame a tools/list. Cada herramienta disponible incluye su nombre y el esquema de argumentos. Valide las solicitudes con los esquemas devueltos antes de llamar a una herramienta.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

Use tools/list para descubrir las herramientas disponibles para su conexión. La disponibilidad depende de los permisos concedidos y del acceso del espacio de trabajo. Empiece con permisos de lectura; pida a un administrador que revise el acceso que falta en lugar de solicitar permisos amplios.

¿Cómo se llama a una herramienta?

Envíe una solicitud tools/call con el nombre completo dureach. y un objeto de argumentos. Los nombres desconocidos o sin el prefijo devuelven Unknown tool (INVALID_PARAMS):

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "dureach.companies.search",
    "arguments": {"query": "industrial valves", "page": 1, "limit": 10}
  }
}

Un resultado correcto devuelve un elemento de texto con JSON más una copia procesada de structuredContent. Un error de aplicación devuelve isError: true con {"error": {"code": "...", "details": {...}}, "request_id": "..."}. Guarde el request_id para soporte y la gestión de reintentos. Los límites completos de argumentos se listan en la Referencia de herramientas MCP.

¿Cómo se configuran los clientes habituales?

Claude Desktop u otros clientes basados en conectores

Añada un servidor HTTP transmitible con la URL https://app.dureach.com/mcp.
Configure la autenticación OAuth con el ID de cliente de su registro OAuth de Dureach y la URL de metadatos del recurso MCP.
Complete el consentimiento y verifique que el conector muestra herramientas que comienzan por dureach..
Comience con dureach.workspace.context y dureach.workspace.capabilities antes de ejecutar búsquedas de datos.

Cliente Python personalizado (SDK oficial `mcp`)

import os

from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client

MCP_URL = "https://app.dureach.com/mcp"
TOKEN = os.environ["DUREACH_OAUTH_ACCESS_TOKEN"]

async def main():
    async with streamable_http_client(
        MCP_URL, headers={"Authorization": f"Bearer {TOKEN}"}
    ) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            tools = await session.list_tools()
            print([t.name for t in tools.tools])
            result = await session.call_tool(
                "dureach.companies.search",
                {"query": "industrial valves", "page": 1, "limit": 10},
            )
            print("Search completed")

Sustituya el token y la consulta por sus propios valores. Nunca guarde el token en el control de versiones.

¿Qué comprobaciones deben ejecutarse antes de compartir el acceso?

Llame a dureach.workspace.context y confirme que el ID del espacio de trabajo y los ámbitos devueltos coinciden con el espacio de trabajo previsto.
Llame a dureach.workspace.capabilities y confirme que solo aparecen las acciones esperadas.
Ejecute una lectura acotada (por ejemplo, companies.search con limit: 5) y confirme los campos de paginación.
Para las operaciones de escritura, ejecute primero una simulación con dry_run: true; consulte Aprobaciones, políticas y cuotas de MCP.
Revoque el token en /oauth/revoke o en Settings → Integrations cuando el acceso ya no sea necesario.