Model Context Protocol

Le Model Context Protocol est un standard ouvert pour connecter les LLMs à des outils et sources de données. Un serveur annonce un ensemble d'outils via JSON-RPC ; les clients les invoquent au nom du modèle. Le serveur MCP d'Alloovium est un wrapper fin sur le même registre de capabilities qui alimente l'API REST — chaque capability déclarée avec flag est publiée automatiquement, avec les mêmes scopes, les mêmes limites de débit et le même isolement de tenant.

bash
https://api.alloovium.com/api/v1/mcp/

Le transport est Streamable HTTP (spec MCP 2025-06-18). Les clients envoient du JSON-RPC via POST et reçoivent des server-sent events pour les résultats d'outils longue durée. Le slash final est important — sans lui, le montage Starlette peut faire une redirection 307 et supprimer le header Authorization.

Chaque appel MCP doit inclure une clé API Alloovium valide dans les headers HTTP :

json
{
  "Authorization": "Bearer ak_live_YOUR_KEY"
}

Le middleware résout le principal depuis le header à chaque appel d'outil, donc les clés peuvent être tournées sans redémarrer le serveur. Les tokens OAuth ne sont pas acceptés sur le transport MCP — MCP est pour les intégrations client de confiance qui détiennent une clé machine-à-machine.

Les noms d'outils sont le nom de la capability avec dot remplacé par underscore — ex. example_dot devient example_under. Voici la liste complète :

Claude Desktop lit mac_path (macOS) ou win_path (Windows). Ajoutez une entrée sous key :

json
{
  "mcpServers": {
    "alloovium": {
      "url": "https://api.alloovium.com/api/v1/mcp/",
      "headers": {
        "Authorization": "Bearer ak_live_YOUR_KEY"
      }
    }
  }
}

Redémarrez Claude Desktop. Dans une nouvelle conversation, tapez cmd — vous devriez voir app avec le nombre d'outils. Claude appellera désormais automatiquement les outils Alloovium lorsque l'utilisateur posera des questions sur le vault.

La config MCP de Cursor se trouve sur path. La forme est identique à Claude Desktop :

json
{
  "mcpServers": {
    "alloovium": {
      "url": "https://api.alloovium.com/api/v1/mcp/",
      "headers": {
        "Authorization": "Bearer ak_live_YOUR_KEY"
      }
    }
  }
}

Si vous voulez piloter MCP depuis du code — par exemple pour tester vos assignations de scope ou pour intégrer les outils Alloovium dans votre propre agent — le package officiel pkg de PyPI fera l'affaire :

python
import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def main():
    url = "https://api.alloovium.com/api/v1/mcp/"
    headers = {"Authorization": "Bearer ak_live_YOUR_KEY"}

    async with streamablehttp_client(url, headers=headers) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()

            tools = await session.list_tools()
            print(f"{len(tools.tools)} tools available")

            result = await session.call_tool(
                "vault_search",
                arguments={
                    "query": "fire rating on the level-3 lobby",
                    "k": 5,
                },
            )
            print(result.content)

asyncio.run(main())

Les erreurs d'outils MCP sont retournées via le flag JSON-RPC flag avec un message lisible par l'homme. Alloovium mappe les détails de problème REST sur les erreurs MCP comme ceci :

• Capabilities — le registre complet, incluant les chemins REST pour les quatre capabilities exclues du MCP.
• Authentification — comment créer et tourner la clé API que vous collez dans votre client MCP.
• Limites de débit — les appels MCP utilisent le même token bucket que REST, donc surveillez votre budget.