# Mikodawa MCP — guía técnica para asistentes

Mikodawa MCP es el servidor oficial para conectar clientes de IA con Mikodawa Suite. Expone operaciones semánticas sobre las APIs reales de las aplicaciones; no ofrece acceso directo a bases de datos.

## Conexión

- Endpoint: `https://mcp.mikodawa.com/mcp`
- Transporte: Streamable HTTP
- Autenticación: OAuth 2.1 Authorization Code con PKCE S256
- Consentimiento: Mikodawa Central, con selección explícita de empresa y permisos
- Descubrimiento OAuth: `https://mcp.mikodawa.com/.well-known/oauth-protected-resource`

No solicites al usuario que copie su contraseña, sesión de Central, access token o refresh token dentro de una conversación. El cliente MCP debe completar OAuth.

## Disponibilidad

| Aplicación |             Tools | Scopes                                                       |
| ---------- | ----------------: | ------------------------------------------------------------ |
| Forge      |      62 `forge_*` | `forge.read`, `forge.write`                                  |
| Atlas      |      46 `atlas_*` | `atlas.read`, `atlas.write`, `atlas.issue`, `atlas.payments` |
| Bridge     |     18 `bridge_*` | `bridge.read`, `bridge.write`, `bridge.communications`       |
| Vault      |       8 `vault_*` | `vault.read`, `vault.signatures`                             |
| Flow       |       13 `flow_*` | `flow.read`, `flow.write`, `flow.execute`                    |
| Sense      | Sin tools propias | Participa mediante Atlas y nodos Flow                        |
| Hub        | Sin tools propias | Experiencia conectada con Bridge                             |
| Signal     | Sin tools propias | No disponible en MCP v1                                      |
| Tower      | Sin tools propias | Participa en Radar de Atlas y nodos Flow                     |

La cifra del catálogo es informativa. Después de autenticar, `tools/list` es la fuente autoritativa: solo devuelve tools compatibles con las aplicaciones activas y los scopes concedidos.

## Modelo de autoridad

Una autorización representa exactamente:

1. Un usuario de Mikodawa.
2. Una empresa seleccionada.
3. Un cliente OAuth.
4. Un conjunto explícito de scopes.

La aplicación de destino vuelve a validar usuario, empresa, suscripción, rol y permiso de módulo. La presencia de una tool en el catálogo no evita las reglas de negocio de la aplicación.

## Reglas de operación para IA

1. Consulta antes de escribir.
2. Resuelve nombres a IDs estables y detente ante coincidencias ambiguas.
3. Crea documentos como borradores; emitir es una acción distinta.
4. Antes de una acción sensible, muestra recurso, empresa, destinatario, importes y efecto.
5. Conserva la misma clave de idempotencia al reintentar una misma intención.
6. No intentes eliminar físicamente documentos fiscales ni evadir las confirmaciones.
7. No expongas secretos, campos internos, enlaces privados o archivos sin autorización.

## Riesgo y confirmación

- R0: lectura sin efecto externo.
- R1: escritura ordinaria y reversible dentro de la aplicación.
- R2: cambio moderado que puede necesitar confirmación conversacional.
- R3: impacto elevado, pago, comunicación externa o acción equivalente.
- R4: acción definitiva, como emitir un documento numerado.

Los scopes conceden una clase de capacidad. No sustituyen la confirmación específica que una operación sensible pueda requerir.

## Composición segura

Un agente puede combinar tools de varias aplicaciones cuando todas están autorizadas. Ejemplos:

- Resolver un cliente en Atlas y vincularlo con Forge.
- Consultar documentos de Atlas y relacionarlos con la situación de un proyecto Forge.
- Preparar un workflow en Flow que use datos de Atlas y envíe una comunicación mediante Bridge.
- Enviar un documento elegible de Atlas a una solicitud de firma de Vault.

Cada paso debe conservar el scope y el nivel de confirmación de su aplicación. No crees una “super-tool” conceptual que omita esos límites.

## Recursos públicos

- Índice para LLM: `https://docs.mikodawa.com/llms.txt`
- Catálogo máquina: `https://docs.mikodawa.com/ai/mcp-catalog.json`
- Guía Atlas: `https://docs.mikodawa.com/ai/atlas-mcp.md`
- Contexto Atlas JSON: `https://docs.mikodawa.com/ai/atlas-context.json`

MCP v1 publica tools. No anuncies `resources/list` o `prompts/list` como capacidades del servidor hasta que aparezcan en su descubrimiento real.