Documentación

Integración MCP

El servidor MCP (Modelo de Protocolo de Contexto) permite que modelos de IA como Claude interactúen con Asset Core a través de llamadas a herramientas mediante JSON-RPC.

Requisitos Previos

  • Daemons de Asset Core en ejecución (escritura y lectura)
  • Cadena de herramientas Rust para construir el servidor MCP
  • Cliente compatible con MCP (Claude Desktop, etc.)

Paso 1 - Construir el servidor MCP

Desde el repositorio de Asset Core:

cargo build --release --bin mcp-server

El binario se encuentra en target/release/mcp-server.

Paso 2 - Configurar las URL del daemon

El servidor MCP se conecta a tus demonios de Asset Core. Configura a través de variables de entorno:

export ASSETCORE_WRITE_URL=http://localhost:8080
export ASSETCORE_READ_URL=http://localhost:8081

Los valores predeterminados son localhost:8080 (escritura) y localhost:8081 (lectura).

Paso 3 - Elegir transporte

El servidor MCP admite dos transportes:

STDIO (predeterminado)

Para la integración directa con Claude Desktop y clientes similares:

./target/release/mcp-server

El servidor lee solicitudes JSON-RPC desde stdin y escribe respuestas en stdout.

SSE (Eventos Enviados por el Servidor)

Para integraciones basadas en la web:

MCP_TRANSPORT=sse MCP_PORT=9000 ./target/release/mcp-server
VariableDescripción
MCP_TRANSPORTstdio (predeterminado) o sse
MCP_PORTPuerto de escucha SSE (requerido para SSE)

Paso 4 - Probar la conexión

Lista de herramientas disponibles:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | ./target/release/mcp-server

Verificar la salud del daemon de escritura:

echo '{"jsonrpc":"2.0","id":2,"method":"assetcore_write_health"}' | ./target/release/mcp-server

Paso 5 - Enviar una transacción

Crear un contenedor a través del servidor MCP:

Guía adicional:

echo '{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "assetcore_commit",
  "params": {
    "operations": [
      {
        "op": "CreateContainer",
        "args": {
          "container_id": 1001,
          "kind": "Standard",
          "owner": null
        }
      }
    ],
    "idempotency_key": "mcp-create-1001"
  }
}' | ./target/release/mcp-server

La respuesta incluye el resultado del commit con números de secuencia.

Paso 6 - Configurar Claude Desktop

Agregue el servidor MCP a su configuración de Claude Desktop:

Guía adicional:

{
  "mcpServers": {
    "assetcore": {
      "command": "/path/to/mcp-server",
      "env": {
        "ASSETCORE_WRITE_URL": "http://localhost:8080",
        "ASSETCORE_READ_URL": "http://localhost:8081"
      }
    }
  }
}

Claude ahora puede utilizar las herramientas de Asset Core en las conversaciones.

Solución de problemas

Errores de “Conexión rechazada”

Los demonios no están en ejecución o las URL son incorrectas. Verifique:

curl http://localhost:8080/v1/health
curl http://localhost:8081/v1/health

Errores de “JSON-RPC no válido”

Asegúrese de que cada solicitud sea un JSON válido en una sola línea. El protocolo MCP utiliza JSON delimitado por saltos de línea.

Herramienta no encontrada

El nombre del método debe coincidir exactamente. Herramientas disponibles:

  • tools/list
  • assetcore_commit
  • assetcore_write_health
  • assetcore_read_health
  • assetcore_read_freshness

Usando acctl

También puedes iniciar el servidor MCP a través de acctl:

acctl adapters --transport stdio

Esto utiliza el descubrimiento de configuración y respeta las variables de entorno ASSETCORE_*.

Próximos pasos