El conector
El conector MCP
El asistente del corredor, hablando con su propio CRM.
Un corredor pega una dirección en su Claude (o su ChatGPT), entra en Orkasa, aprueba unos permisos — y a partir de ahí pregunta por sus expedientes y actúa sobre ellos, en sus palabras.
https://orkasa.app/api/mcp
No es una segunda API. Pasa por la misma autenticación que
/api/v1, los mismos permisos, el mismo límite de
peticiones, y —en las cuatro herramientas que escriben— los mismos núcleos que
llaman las rutas REST.
Lo que cambia es la forma de la respuesta: expedientes y jornadas ya compuestos, en vez de filas de tablas. Quien llama es un modelo de lenguaje, y cada unión que le obligas a hacer a mano es una unión que puede equivocarse.
Las nueve herramientas
| Herramienta | Permiso | Qué responde |
|---|---|---|
buscar | leads:read | « ¿Tienes el teléfono de la señora Herrera? » — clientes y propiedades por nombre, teléfono, correo, dirección. |
ver_expediente | leads:read | « ¿Cómo va lo de Felipe? » — el expediente entero: operaciones, etapa, bien, visitas, ofertas, documentos, últimos mensajes, y el próximo gesto del Copiloto. |
mi_jornada | operations:read | « ¿Qué tengo hoy? » — los próximos gestos, el turno propio primero, lo más atrasado delante. |
buscar_propiedades | properties:read | « ¿Qué tengo en Chapinero por debajo de 600 millones? » |
agenda | viewings:read | « ¿Qué visitas tengo esta semana? » |
crear_lead | leads:write | Un contacto dictado, con su operación de compra o alquiler abierta. |
agendar_visita | viewings:write | Una visita, confirmada en el huso horario de la agencia. |
avanzar_etapa | operations:write | Un paso de pipeline, compuertas incluidas. |
registrar_oferta | offers:write | Una oferta recibida, sin aceptarla ni mover la etapa. |
Los detalles de cada una están en Herramientas.
Los nombres de las herramientas están en español: es lo que el modelo
empareja con la intención del corredor. Los nombres de los campos siguen
siendo los de /api/v1. Un lead_id que significara una cosa aquí y otra en
REST es la clase de desviación que nadie nota hasta que una integración se
rompe.
El protocolo
Streamable HTTP, sin estado. Cinco métodos: initialize,
notifications/initialized, ping, tools/list, tools/call. No hay sesión,
no hay flujo SSE, no hay nada que reanudar: cada POST lleva su propio token y
se responde solo, así que dos llamadas seguidas pueden aterrizar en dos
instancias distintas sin que nadie lo note. El GET que abriría un servidor con
estado responde 405.
initialize responde antes del token: un cliente que todavía no tiene
credencial necesita poder averiguar qué versión del protocolo hablamos, y
oponerle un 401 manda a algunos clientes a un bucle de reintentos en lugar de
al flujo OAuth.
Comprobarlo a mano
curl -s https://orkasa.app/.well-known/oauth-protected-resource | jq
curl -s -i -X POST https://orkasa.app/api/mcp \
-H 'content-type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | head -12La segunda devuelve 401 con el reto que arranca el descubrimiento — ver
Conectar un asistente.