# Servidor MCP de Nemphi

> Conecta Claude, ChatGPT, Cursor o cualquier cliente MCP a tu empresa en Nemphi. Dirección del servidor, inicio de sesión, modo código, aprobaciones y solución de problemas.

Tu asistente de IA trabaja en tu empresa con las mismas reglas, permisos por rol, aprobaciones y bitácora que la app.

## Qué es

El servidor MCP de Nemphi es un servidor remoto del [Model Context Protocol](https://modelcontextprotocol.io). Deja que un asistente de IA (Claude, ChatGPT, Cursor o cualquier cliente MCP) consulte y trabaje en tu empresa en Nemphi.

No es una puerta aparte. Cada llamada pasa por la misma tubería que la app: el permiso de tu rol, las políticas de autonomía de tu empresa, las aprobaciones y la bitácora de acciones. Lo que no puedes hacer en la app, el asistente tampoco puede hacerlo en tu nombre.

Dirección del servidor: `https://api.nemphi.com/mcp`. Transporte Streamable HTTP, sin sesión: cada petición es un POST independiente.

## Conectar en Claude y otros clientes

**Claude (web, escritorio y móvil).** Abre claude.ai, ve a Configuración › Conectores y busca Nemphi en el directorio. Si todavía no aparece, elige "Agregar conector personalizado" y pega `https://api.nemphi.com/mcp`. Claude te lleva a iniciar sesión en Nemphi; elige la empresa y acepta en la pantalla de consentimiento. Los conectores se comparten entre la web, la app de escritorio y la móvil.

**Claude Code.** Un comando:

```sh
claude mcp add --transport http nemphi https://api.nemphi.com/mcp
```

Al primer uso, Claude Code abre el navegador para iniciar sesión.

**ChatGPT, Cursor y otros.** Sirve cualquier cliente que hable Streamable HTTP y OAuth 2.1 con PKCE (S256). El servidor acepta registro dinámico de clientes y Client ID Metadata Documents, así que no necesitas pedirnos un client id. Los metadatos están en `https://api.nemphi.com/.well-known/oauth-protected-resource`.

## Autenticación

Hay dos formas de identificarse.

**OAuth.** Es la que usan los conectores. Dos alcances: `tools:read` solo permite herramientas de lectura; `tools` permite leer y escribir. El token de acceso dura 1 hora y el de actualización 30 días; cada actualización entrega un token nuevo e invalida el anterior.

**Llave de API.** Crea una en Nemphi, en Desarrolladores › Llaves API, y envíala en la cabecera `Authorization: Bearer nk_…`. La llave hereda el rol que le asignes.

Para retirar el acceso, desconecta el conector en el cliente o revoca la autorización o la llave desde Nemphi. Las dos cosas surten efecto en la siguiente llamada.

## Modo código

Nemphi tiene cerca de 550 herramientas. Entregárselas todas al modelo gasta contexto y empeora la elección, así que el servidor expone tres herramientas y el asistente escribe código que llama a las demás.

| Herramienta | Qué hace | Argumentos |
| --- | --- | --- |
| `search_tools` | Busca herramientas de Nemphi por palabra clave. Solo lectura. | `{ "query": string, "module"?: string, "limit"?: number }`. `limit` va de 1 a 20; por defecto 8. |
| `run_read_code` | Ejecuta un fragmento de JavaScript que solo puede llamar herramientas de lectura. | `{ "code": string }` |
| `run_code` | Igual, y además puede llamar herramientas que cambian datos. Cada llamada sigue pasando por las políticas y aprobaciones de la empresa. | `{ "code": string }` |

`search_tools` devuelve, por cada coincidencia, el nombre, el título, la descripción, la clase de riesgo y el esquema JSON de entrada.

Dentro del fragmento:

- `nemphi.call(toolName, input)` llama una herramienta de forma sincrónica y devuelve su resultado JSON. Si la llamada se rechaza, lanza un `Error` cuya propiedad `code` dice por qué: `approval_required`, `policy_denied`, `invalid_input`, entre otros.
- Lo que escribas con `console.log(...)` vuelve en `logs`.
- El valor de la última expresión del fragmento vuelve en `result`. Un `return` suelto al nivel superior no funciona; termina con la expresión que quieres devolver.

Límites por ejecución: 30 segundos, 64 MB de memoria, 50 llamadas a herramientas y un resultado recortado a 100 KB. No hay red, sistema de archivos, temporizadores ni `import`.

Ejemplo, con `run_read_code`:

```js
const drafts = nemphi.call("invoices.list", { status: "draft" });

drafts.invoices.map((invoice) => ({
  number: invoice.number,
  total_cents: invoice.total_cents,
}));
```

**Catálogo completo.** Un cliente que prefiera una herramienta MCP por cada herramienta de Nemphi puede conectarse a `https://api.nemphi.com/mcp?tools=all`. Los nombres son los de Nemphi, por ejemplo `invoices.list`. Es la misma pipeline; solo cambia la forma de la lista.

## Aprobaciones y seguridad

Las herramientas de lectura se ejecutan de inmediato.

Las que contabilizan, pagan, publican o envían algo fuera de Nemphi, y las que cambian lo que los agentes pueden hacer por su cuenta, siguen las políticas de la empresa. Cuando una llamada necesita la aprobación de una persona, devuelve `approval_required`. El asistente debe decírselo a su usuario; la persona decide en la Bandeja de Nemphi y el asistente reintenta o sigue con otra cosa. Un asistente nunca aprueba por sí mismo.

**Empresas creadas por un agente.** Cuando la empresa y su llave de API las creó un agente al registrarse por su cuenta, su usuario rara vez tiene la app abierta. En esas empresas una llamada que necesita aprobación no se pierde: queda guardada como aprobación pendiente, y la respuesta trae el id de la aprobación y un resumen corto para que el agente se lo muestre a su usuario. El agente transmite la respuesta con dos herramientas MCP: `approvals.pending` lista las aprobaciones pendientes y `approvals.decide` aprueba o niega una. En modo código son `nemphi.call("approvals.pending", {})` y `nemphi.call("approvals.decide", { … })` dentro de `run_code`. Nemphi ejecuta entonces la herramienta en nombre del dueño y la bitácora marca la acción como "aprobada a través del asistente". El dueño sigue pudiendo decidir o reversar desde la Bandeja de Nemphi, y revocar la llave corta la transmisión.

Las compras que mueven dinero (comprar un dominio, cambiar el plan o el consumo extra) no están disponibles por MCP. Se hacen en la app.

Cada llamada queda en la bitácora de acciones con el actor "Cliente MCP", el nombre de quien autorizó la conexión, la herramienta y el resultado.

## Qué pedirle a tu asistente

- "¿Qué facturas están vencidas este mes y a quién hay que cobrar?"
- "Crea un borrador de factura para Comercial Los Andes por 12.480.000 COP con el concepto de la cotización 231."
- "Resume los gastos por categoría del trimestre y compáralos con el anterior."
- "¿Qué tareas del proyecto Bodega Norte están sin responsable?"
- "Registra en el CRM que hablé hoy con Paula de Distribuciones Andina y que llamo el martes."

## Solución de problemas

**401 o "unauthorized".** El token venció o se revocó. Vuelve a conectar el conector, o crea una llave nueva si usabas una.

**`approval_required`.** La llamada espera a una persona. Abre la Bandeja de Nemphi, decide, y pide al asistente que reintente. En una empresa creada por un agente, también puedes responderle al asistente y él transmite tu decisión con `approvals.decide`.

**La herramienta no aparece o `policy_denied`.** Tu rol no alcanza esa herramienta, o el token se emitió con `tools:read` y la herramienta escribe. Pide el permiso a un administrador o vuelve a conectar con el alcance `tools`.

**`invalid_input`.** El asistente envió un argumento que la herramienta no acepta. El mensaje de error dice cuál; `search_tools` devuelve el esquema exacto.

## Privacidad y soporte

Nemphi recibe solo las llamadas a herramientas que el asistente hace: el nombre de la herramienta y sus argumentos. No lee tus conversaciones ni el resto del contexto del asistente. Lo que el proveedor del asistente haga con las respuestas lo rigen sus propios términos.

El tratamiento de datos está en la [política de privacidad](https://www.nemphi.com/legal/privacy). Para dudas o problemas, escribe a [hola@nemphi.com](mailto:hola@nemphi.com).