# Panorama general y

El **Maetra MCP servidor** da acceso basado en la capacidad de los clientes de Modelo Context Protocol a Task Guard, Govern y Secure usando la misma clave de API del espacio de trabajo que la API de REST.

Un agente conectado puede anclar el trabajo a una tarea autorizada por el usuario, comprobar si las acciones propuestas permanecen alineadas, el contenido de la exploración, la evaluación de políticas o la aprobación humana, consumir una aprobación para una ejecución exacta, y preservar los intentos de proveedor y los efectos observados.

### Comience con el flujo que necesita

Comienza con aprobación. Crear una clave de API y llamar `request_approval` antes de una acción gobernada. Si su integración sólo necesita la decisión de aprobación, este es el flujo básico.

Para conectar esa decisión a lo que va después, utilice los recibos de ejecución. Agregue tres llamadas: autorice la solicitud exacta, registre cada intento de proveedor y registre lo que cambió. Su clave de API y la conexión de MCP siguen siendo reutilizables. Sólo una vez se puede utilizar la autorización para esa ejecución aprobada específica.

El punto final de MCP es:

```
https://mcp.maetra.io/mcp
```

### De un vistazo

|                     |                                               |
| ------------------- | --------------------------------------------- |
| **Nombre del servidor** | `maetra-mcp` |
| **Versión** | `1.0.0` |
| **Protocolo de MCP** | `2024-11-05` |
| **Transporte** | HTTP, JSON-RPC 2.0 sobre `POST` |
| **Punto final** | `POST https://mcp.maetra.io/mcp` |
| **Auth** | `Authorization: Bearer maetra_...` (requerido) |
| **Streaming (SSE)** | No está habilitada — sólo la solicitud/respuesta |
| **Salud** | `GET /health` |

### Autenticación y acceso a la capacidad

Cada solicitud de MCP lleva una clave de API de espacio de trabajo:

```
Authorization: Bearer maetra_xxxxxxxxxxxxxxxxxxxx
```

Sin una clave válida, el servidor devuelve el error JSON-RPC `-32001`. El acceso a MCP Workspace también debe ser habilitado. La llave [alcances](https://maetra.io/es/docs/getting-started/authentication), los derechos del módulo y la configuración del espacio de trabajo determinan qué herramientas están disponibles.

Al comienzo de cada nuevo ciclo de trabajo o giro del usuario —y después de la compactación del contexto, reiniciar o un refresco de acceso— llamó:

```
get_mcp_access
```

Devuelve:

* el habilitado `secure`, `govern`, y `task_guard` capacidades
* las herramientas exactas actualmente permitidas para cada capacidad
* comportamiento de acogida
* a corto plazo `mcp_access_token`
* la caducidad de la señal

Pasa eso. `mcp_access_token` a cada llamada de la herramienta de la capacidad de Maetra más tarde. `get_mcp_access` es la única herramienta que no la requiere.

> **Important**
> No cachee la capacidad a través de los ciclos de trabajo. Refrésalo con `get_mcp_access`, y nunca llame a una herramienta cuya capacidad está deshabilitada en el documento de acceso devuelto.


### Herramientas que dependen de la capacidad

`tools/list` es dinámico. Siempre incluye `get_mcp_access`, entonces incluye sólo las herramientas permitidas para el espacio de trabajo actual y la clave. Un espacio de trabajo con cada capacidad habilitada puede recibir hasta 18 herramientas.

| Capacidad | Herramientas |
| ---------- | ----- |
| Acceso | `get_mcp_access` |
| Task Guard | `start_task`, `get_task_context`, `check_task_alignment`, `explain_task_relationship`, `record_task_progress`, `record_action_effect`, `complete_task` |
| Secure | `check_action`, `list_active_rules`, `create_rule`, `update_rule` |
| Govern | `request_approval`, `get_approval_status`, `list_active_policies`, `authorize_execution`, `record_execution_attempt`, `record_execution_effect` |

Ver el [Referencia de herramientas](https://maetra.io/es/docs/mcp-server/tools-reference) para los insumos y el comportamiento necesario.

### Conectar a un cliente

#### Claude Desktop / Code

Agregue el servidor HTTP a su cliente de MCP config:

```json
{
  "mcpServers": {
    "maetra": {
      "type": "http",
      "url": "https://mcp.maetra.io/mcp",
      "headers": {
        "Authorization": "Bearer maetra_xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

#### Raw JSON-RPC

```bash
curl -X POST https://mcp.maetra.io/mcp \
  -H "Authorization: Bearer $MAETRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0", "id": 1, "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": { "name": "my-agent", "version": "0.1.0" }
    }
  }'

curl -X POST https://mcp.maetra.io/mcp \
  -H "Authorization: Bearer $MAETRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }'
```


### Métodos de apoyo de JSON-RPC

| Método | Comportamiento |
| ----------------- | --------- |
| `initialize` | Devuelve las capacidades del servidor e instrucciones para los controles de Maetra habilitados. |
| `tools/list` | Devoluciones `get_mcp_access` y las herramientas de capacidad actualmente permitidas. |
| `tools/call` | Invoca una herramienta llamada con una `arguments` objeto. |
| `ping` | Mantener la vida; devoluciones `{}`. |
| `notifications/*` | Aceptado y reconocido sin un órgano de respuesta. |

El servidor soporta las solicitudes de JSON-RPC batidas. No hornear una herramienta de la capacidad con la `get_mcp_access` La llamada depende, porque la solicitud posterior necesita el token devuelto por el preflight.