# Vue d'ensemble et connexion

Les **Serveur Maetra MCP** offre aux clients Model Context Protocol un accès basé sur les capacités à Task Guard, Govern et Secure en utilisant la même clé API espace de travail que l'API REST.

Un agent connecté peut ancrer le travail à une tâche autorisée par l'utilisateur, vérifier si les actions proposées restent alignées, analyser le contenu, demander l'évaluation des politiques ou l'approbation humaine, consommer une approbation pour une exécution exacte, et préserver les tentatives du fournisseur et les effets observés.

### Commencez par le flux dont vous avez besoin

Commencez par l'approbation. Créer une clé et un appel d'API `request_approval` avant une action régie. Si votre intégration n'a besoin que de la décision d'approbation, c'est le flux de base.

Pour relier cette décision à ce qui se passe après, utilisez les reçus d'exécution. Ajouter trois appels : autoriser la demande exacte, enregistrer chaque tentative du fournisseur et enregistrer ce qui a changé. Votre clé API et la connexion MCP restent réutilisables. Seule l'autorisation pour cette exécution approuvée spécifique peut être utilisée une fois.

Le point final d'MCP est :

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

### En un coup d'oeil

|                     |                                               |
| ------------------- | --------------------------------------------- |
| **Nom du serveur** | `maetra-mcp` |
| **Version** | `1.0.0` |
| **Protocole MCP** | `2024-11-05` |
| **Transports** | HTTP, JSON-RPC 2.0 sur `POST` |
| **Point d'arrivée** | `POST https://mcp.maetra.io/mcp` |
| **Resp.: Ministère de l'Agriculture** | `Authorization: Bearer maetra_...` (obligatoire) |
| **Diffusion en continu (SSE)** | Non activé — demande/réponse seulement |
| **Santé** | `GET /health` |

### Authentification et accès aux capacités

Chaque requête MCP porte une clé API espace de travail :

```
Authorization: Bearer maetra_xxxxxxxxxxxxxxxxxxxx
```

Sans clé valide, le serveur retourne l'erreur JSON-RPC `-32001`C'est vrai. L'accès à l'espace de travail MCP doit également être activé. La clé est [champ d'application](https://maetra.io/fr/docs/getting-started/authentication), les droits de module et la configuration de l'espace de travail déterminent quels outils sont disponibles.

Au début de chaque tour d'utilisateur ou cycle de travail — et après compactage du contexte, redémarrage ou rafraîchissement de l'accès — appel:

```
get_mcp_access
```

Il retourne :

* la valeur activée `secure`, `govern`et `task_guard` Capacités
* les outils exacts actuellement autorisés pour chaque capacité;
* comportement requis de l'hôte
* une courte durée `mcp_access_token`
* l'expiration du jeton

Passe ça. `mcp_access_token` à chaque appel ultérieur de l'outil de capacité Maetra. `get_mcp_access` est le seul outil qui ne l'exige pas.

> **Important**
> Ne cachez pas le jeton de capacité à travers les cycles de travail. Rafraîchis-le avec `get_mcp_access`, et ne jamais appeler un outil dont la capacité est désactivée dans le document d'accès retourné.


### Outils dépendant des capacités

`tools/list` est dynamique. Il comprend toujours `get_mcp_access`, comprend alors seulement les outils autorisés pour l'espace de travail et la clé en cours. Un espace de travail avec toutes les capacités activées peut recevoir jusqu'à 18 outils.

| Capacité | Outils |
| ---------- | ----- |
| Accès | `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` |

Voir [Référence des outils](https://maetra.io/fr/docs/mcp-server/tools-reference) pour les intrants et le comportement requis.

### Connexion d'un client

#### Claude Desktop / Code

Ajoutez le serveur HTTP à votre configuration client MCP :

```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éthodes d'JSON-RPC supportées

| Méthode | Comportement |
| ----------------- | --------- |
| `initialize` | Retourne les fonctionnalités du serveur et les instructions pour les commandes Maetra activées. |
| `tools/list` | Retourne `get_mcp_access` et les outils de capacité actuellement autorisés. |
| `tools/call` | Invoque un outil nommé avec un `arguments` objet. |
| `ping` | Garder en vie; retourner `{}`. |
| `notifications/*` | Accepté et reconnu sans organisme de réponse. |

Le serveur prend en charge les requêtes d'JSON-RPC par lots. Ne pas loter un outil de capacité avec le `get_mcp_access` appeler cela dépend, parce que la demande plus tard a besoin du jeton retourné par le prévol.