Documentación de First Plug MCP
First Plug MCP es un servidor remoto de Model Context Protocol que da a los asistentes de IA acceso de solo lectura a un workspace de First Plug: colaboradores, equipos, envíos, cotizaciones y registros del workspace. Lo construye y opera First Plug sobre su API pública (/api/v1).
Inicio rápido
Agregá la URL del servidor en tu herramienta de IA, ingresá a First Plug en la ventana del navegador que se abre y aprobá el acceso. No hay nada para copiar ni pegar.
Claude
Configuración → Conectores → Agregar conector personalizado, pegá la URL y hacé clic en Conectar:
https://mcp.firstplug.co/mcp
ChatGPT
Configuración → Apps → Configuración avanzada, activá el modo desarrollador y creá una app con la URL:
https://mcp.firstplug.co/mcp
Claude Code
Corré en una terminal y después /mcp para ingresar:
claude mcp add --transport http firstplug https://mcp.firstplug.co/mcp
Cursor
Settings → MCP → Add new MCP server, o ~/.cursor/mcp.json:
{ "mcpServers": { "firstplug": { "url": "https://mcp.firstplug.co/mcp" } } }Otros clientes
Cualquier cliente que soporte servidores MCP remotos por Streamable HTTP con OAuth:
https://mcp.firstplug.co/mcp
Autenticación
El conector usa OAuth 2.1 con PKCE y registro dinámico de clientes. Aprobás el acceso una vez y la sesión se renueva sola.
- 1Tu herramienta de IA llama al servidor y recibe un 401 con la metadata del recurso protegido.
- 2La herramienta se registra y abre First Plug Connect en el navegador.
- 3Ingresás con tu cuenta de First Plug y aprobás el acceso para tu workspace.
- 4First Plug crea una key para la conexión de servidor a servidor. La key nunca pasa por el navegador ni por la herramienta de IA: viaja sellada (AES-256-GCM) dentro de los tokens.
- 5La herramienta recibe un access token (válido por una hora) y un refresh token. El servidor no tiene estado y no guarda datos de sesión.
Herramientas
Cada herramienta tiene la anotación readOnlyHint: true y solo lee datos. En v1 ninguna herramienta crea, modifica ni borra nada.
searchSearchreadOnlyHintPersonas por nombre o email, equipos por nombre o serie y envíos por número de orden, todo junto. Punto de entrada cuando solo tenés un nombre.
querycountrycityteamget_member_overviewMember overviewreadOnlyHintTodo sobre una persona: contacto y dirección, equipo, equipos asignados, envío activo y estado de offboarding.
member_idlist_membersList membersreadOnlyHintLista y cuenta personas con filtros. Los totales son exactos para los filtros.
statusteamcountrycitysearchresume_cursorscan_alllist_assetsList assetsreadOnlyHintRecorre y cuenta la flota: estado, categoría, ubicación, país del holder, garantía, MDM, condición.
statuscategorycondition…resume_cursorscan_alltrack_assetTrack assetreadOnlyHintUn equipo: ubicación y holder actual, precio, specs, envío activo e historial de envíos.
asset_idlist_shipmentsList shipmentsreadOnlyHintEnvíos con estado, tramos, precio, tracking y los campos exactos que los frenan.
idstatusorder_idasset_idtrack_quotesTrack quotesreadOnlyHintPedidos de cotización: estado, precio cotizado con desglose, la orden generada y motivos de rechazo.
idsearchget_recordsGet recordsreadOnlyHintEntidades secundarias: teams, oficinas, actividad (audit log), webhooks y configuración.
entityidresume_cursorscan_allLos nombres de las herramientas tienen 64 caracteres o menos y cada una tiene un título legible.
Recursos
Contexto de solo lectura que el asistente puede cargar antes de llamar herramientas.
fp://session/whoami | Contexto de la sesión: workspace, scopes y mcp_version. |
fp://tenant/overview | Conteos del workspace de un vistazo. |
fp://attention/queue | Ítems que requieren atención (resumen + top 20). |
fp://attention/blocking-shipments | Colaboradores con datos faltantes que frenan un envío. |
fp://offices | Lista de oficinas. |
fp://{member|shipment|asset|office|quote|team}/{id} | Detalle de una entidad. |
Datos y privacidad
El conector solo lee el workspace que aprobó la persona que lo conectó. Todas las conexiones reciben el mismo conjunto fijo de permisos de solo lectura, sin importar el rol de esa persona.
Qué lee el conector
- Colaboradores: nombre, email laboral y personal, teléfono, puesto, fecha de ingreso, equipo, oficina, país y ciudad, dirección de entrega, equipos asignados, estado de offboarding.
- Equipos: modelo, serie, categoría, estado, condición, garantía, ubicación, holder, precio.
- Envíos: estado, origen y destino, fechas, tracking, precio, campos faltantes.
- Cotizaciones: estado, precio cotizado y desglose, orden generada, motivo de rechazo.
- Workspace: teams, oficinas, registro de actividad, webhooks y configuración.
Qué nunca hace
- Nunca recibe tu conversación ni tus prompts: solo las llamadas a herramientas de tu asistente.
- Nunca escribe, modifica ni borra datos en v1.
- Nunca guarda datos de tu workspace: el servidor no tiene estado ni base de datos.
- Nunca expone la API key al navegador ni a la herramienta de IA.
Los logs operativos registran el nombre de la herramienta, las páginas leídas y el tamaño de la respuesta, para confiabilidad. Las conexiones se revocan en Integraciones → API keys. Política de privacidad · Términos del servicio
Límites y versiones
- Las herramientas de listado devuelven una página de la API por defecto. El asistente usa resume_cursor, o scan_all=true, cuando necesitás más.
- Los conteos usan summary.total, que es exacto para los filtros aplicados.
- Aplican los rate limits de la API pública de First Plug.
- La versión del servidor se informa en GET /health y en fp://session/whoami.
GET https://mcp.firstplug.co/health
→ { "ok": true, "mcp_version": "1.0.0", "auth": "oauth", … }