Dataverse Local MCP

Conecta Claude (o cualquier cliente MCP) a tu entorno de Microsoft Dataverse / Dynamics 365 y trabaja con tus datos en lenguaje natural: consulta registros, ejecuta tus vistas guardadas, explora tablas y columnas, crea y actualiza filas.

• Inicia sesión como siempre — con tu propia cuenta de trabajo de Microsoft, en tu navegador, con el mismo inicio de sesión de confianza que usa XrmToolBox. Funciona sin configuración adicional: sin registro de aplicación, sin claves de API, sin preparación de administrador.

• Rápido desde la segunda llamada — el esquema de tu entorno y las vistas guardadas se precargan y se almacenan en caché localmente, por lo que las preguntas sobre metadatos se responden al instante.

• Caja de herramientas completa — consultas OData, FetchXML (agregados y combinaciones), CRUD de entidades y descubrimiento de metadatos en un solo servidor.

Guías: Configuración · Guía de usuario

Primeros pasos

1. Instala Node.js 18 o superior si no lo tienes.

2. Instala el servidor desde la página de instalación de npm:

npm install -g dataverse-local-mcp

(O omite la instalación y usa npx -y dataverse-local-mcp como comando a continuación).

3. Añádelo a tu cliente MCP — para Claude Desktop, añade esto a claude_desktop_config.json, reemplazando la URL con la de tu entorno:

{
  "mcpServers": {
    "dataverse": {
      "command": "dataverse-local-mcp",
      "args": ["https://yourorg.crm.dynamics.com"]
    }
  }
}

4. Inicia sesión una vez. La primera vez que se ejecuta una herramienta, tu navegador abre un inicio de sesión de Microsoft: elige tu cuenta de trabajo para ese entorno. El token se guarda en caché en ~/.dataverse-mcp/token-cache.json, por lo que no se te volverá a pedir hasta que expire. Si el navegador te inicia sesión con la cuenta incorrecta, siempre se muestra un selector de cuentas para que puedas cambiar.

Pruébalo: pide a tu cliente MCP que ejecute la herramienta whoami — debería devolver tu UserId y OrganizationId de Dataverse. Luego prueba "listar mis vistas guardadas en cuenta" o "muéstrame las 5 cuentas principales por nombre".

Related MCP server: Dataverse MCP Server

Herramientas

Datos

Esquema

Anotaciones

Entorno

Escritura segura

Toda herramienta que modifica datos previsualiza por defecto. Si se llama sin confirm: true, describe exactamente qué cambiaría — nombrando el registro resuelto por su nombre principal — y no llama a nada. delete además lista los valores de campo actuales del registro, para que puedas ver lo que está a punto de perderse.

• Un registro a la vez. update y delete toman un id o un filtro where, y cualquier coincidencia con más de un registro se rechaza listando los candidatos en lugar de expandirse.

• Concurrencia optimista por defecto. Las actualizaciones y eliminaciones llevan el ETag del registro, por lo que una escritura contra un registro que cambió después de que lo leyeras falla en lugar de sobrescribir silenciosamente el trabajo de otra persona. Pasa concurrency: false para optar por no participar.

• Las cargas útiles se verifican antes de enviarse. Columnas desconocidas, columnas no válidas para la operación, valores de conjuntos de opciones fuera de rango y propiedades de navegación @odata.bind desconocidas fallan localmente con un mensaje que nombra el problema — no un 400 opaco de la plataforma.

• Las acciones tienen efectos en cascada. Gran parte del trabajo real en Dataverse ocurre a través de acciones en lugar de escrituras de tablas, y sus efectos van más allá de lo que sugiere la llamada. La previsualización muestra la llamada, no sus consecuencias: estas no se pueden conocer sin ejecutarla.

Los errores muestran el código hexadecimal y el mensaje de Dataverse, con formas reconocidas (privilegio denegado, detección de duplicados, rechazo de regla de negocio o plugin, concurrencia, columna desconocida) precedidas por una línea en lenguaje sencillo. Cualquier cosa no reconocida se transmite tal cual en lugar de adivinarse.

Recursos

El esquema completo $metadata OData (CSDL/EDMX) del entorno se expone como recurso MCP en dataverse://metadata (application/xml, a menudo varios MB).

Cómo funciona la caché

Justo después del protocolo de enlace stdio, el servidor construye sus cachés en segundo plano. Nunca abre un navegador al inicio: la precarga usa solo autenticación silenciosa, por lo que sin un token en caché espera y reintenta después de que tu primera llamada a una herramienta inicie sesión. Nada se bloquea en ello — un arranque en frío sigue funcionando, solo más lento en la primera llamada.

Todo está claveado por OrganizationId, no por la URL del entorno, porque las URLs cambian y los ids de organización no:

~/.dataverse-mcp/
  token-cache.json
  environments/
    index.json                 # host -> organizationId, so a warm start needs no network
    <organizationId>/
      config.json              # url, friendly name, mode, storage, scope, sampling
      schema.json              # cached metadata          } these two follow
      schema.fingerprint       # hash for drift detection } your storage choice
      annotations.md           # your documentation       }
      metadata.xml             # the $metadata resource   } always local:
      saved-queries.json       #                          } large, derived, cheap to refetch

config.json e index.json siempre permanecen locales — contienen la configuración de almacenamiento en sí, por lo que no pueden vivir dentro del backend que describen.

Alcance. Cada tabla recibe un resumen económico a nivel de nombre. El detalle completo de columnas y relaciones se guarda en caché para todas las tablas personalizadas más una lista blanca de las estándar (Field Service y ventas/servicio principales por defecto), limitado a maxFullTables. Cualquier otra cosa se obtiene de forma diferida y se fusiona la primera vez que una herramienta la toca.

Muestreo de filas está desactivado por defecto. Actívalo por entorno y la caché también registra, por columna, la tasa de relleno y hasta cinco valores de ejemplo de un máximo de 20 filas — la señal más útil para tablas cuyas descripciones están en blanco. Lee datos reales, por lo que sigue siendo opcional, y nunca muestrea columnas cuyo tipo o formato sugiera datos personales a menos que lo permitas explícitamente.

Anotaciones

Las descripciones de Dataverse suelen estar en blanco. La forma del propio entorno lleva la mayor parte del significado; el resto es conocimiento humano que vale la pena acumular en lugar de volver a derivar en cada sesión. Las anotaciones viven en markdown plano en environments/<organizationId>/annotations.md — editable por humanos, con diff, y seguro para incluir en un repositorio de compromiso.

## rsm_cipscenariocandidate

Candidate records for capital improvement plan scenario modelling. Populated by
the scenario engine, not by users directly.

_author: ben.vollmer_ · _added: 2026-08-20_ · _confidence: confirmed_ · _provenance: human_

### rsm_scenariotype

Picklist. 1 = replacement, 2 = rehabilitation, 3 = deferral.

_author: ben.vollmer_ · _added: 2026-08-20_ · _confidence: inferred_ · _provenance: human_

Cada anotación lleva dos campos independientes. Confianza es confirmed solo cuando un humano lo declaró; cualquier cosa que un modelo o herramienta dedujo es inferred — que es exactamente por qué las anotaciones nunca se escriben de vuelta en las descripciones de Dataverse por defecto. Procedencia es human, preflight, velocity o model, y gobierna el comportamiento de sobrescritura en un nuevo escaneo: un escritor puede reemplazar libremente su propia nota anterior, y un humano reemplaza cualquier cosa, pero nada más sobrescribe. Cuando un nuevo escaneo contradice la nota de una persona, ambas se conservan y se marcan para que un humano las resuelva en lugar de que una gane silenciosamente.

Las notas creadas por herramientas se representan como citas en bloque para que puedas ver de un vistazo lo que proviene de una persona:

### rsm_scenariotype

> No plugins are registered on this column.

_author: preflight_ · _added: 2026-08-20_ · _confidence: confirmed_ · _provenance: preflight_

Compartir. export_annotations escribe el archivo donde quieras; import_annotations lee uno de vuelta. El front matter lleva el organizationId, y una importación en una organización diferente se rechaza, nunca se fusiona. Cuando ambos lados anotan el mismo objetivo con texto diferente, ambos se conservan y se marcan en lugar de que uno gane silenciosamente.

Deriva. Se captura una huella digital del esquema en el momento de la caché. Cuando cambia, cada anotación se resuelve como valid (válida), changed (cambiada; el tipo o conjunto de opciones se movió debajo de la nota) u orphaned (huérfana; el objetivo ha desaparecido). Se registra un breve resumen al conectar, la advertencia específica se repite en línea en describe_table, y nunca se elimina nada automáticamente.

Modos. Se establecen explícitamente por entorno, nunca se infieren de los privilegios — los privilegios suelen ser más amplios que la intención. consumer (el predeterminado) mantiene las anotaciones locales y nunca escribe metadatos. maker permite además promover una anotación confirmada a la propia descripción de Dataverse.

Promover documentación en Dataverse

Si eres dueño del esquema de un entorno, una anotación confirmada puede convertirse en la descripción real de Dataverse. Esto es deliberadamente incómodo y la fricción no debe reducirse por conveniencia: requiere modo maker, una anotación confirmada (las inferencias se rechazan), sin conflicto sin resolver sobre ella, un objetivo por llamada, y una confirmación explícita después de leer la previsualización.

El texto escrito va prefijado con un marcador [dataverse-mcp] más la procedencia y la fecha. Ese marcador es el punto clave: sin él, una nota promovida se vuelve indistinguible de una descripción escrita por una persona seis meses después, y algo que parecía una suposición razonable empieza a leerse como un hecho.

La promoción es una escritura de metadatos: crea una personalización no administrada en la capa de solución activa, que puede enmascarar actualizaciones posteriores de un componente administrado, y puede ser necesaria la publicación antes de que la descripción aparezca en la interfaz. La vista previa lo indica todo antes de que confirmes, y la herramienta no puede deshacerlo.

Dónde vive tu documentación

Por defecto, todo queda bajo ~/.dataverse-mcp. Puedes cambiarlo con set_storage y tanto las anotaciones como la caché de metadatos se mueven juntas: siempre viajan juntas, por entorno.

Las variantes con respaldo en archivos son una misma implementación: una bóveda de Obsidian, una carpeta sincronizada de OneDrive y un directorio de Basic Memory son, al fin y al cabo, carpetas, y git añade un paso de confirmación. Cada entorno tiene su propia subcarpeta (dataverse-mcp/<friendlyName>-<orgId>) para que una bóveda o repositorio compartido pueda albergar varios sin colisiones.

Notion necesita un token de integración interna en una variable de entorno NOTION_TOKEN — configúralo en el cliente MCP, no en un archivo — y un notionPageId para la página principal, que debe estar compartida con tu integración. Cada línea de Markdown se convierte en un bloque de párrafo, así que el documento hace el viaje de ida y vuelta exactamente y sigue siendo legible y editable en Notion. Como Notion es un almacén de documentos y no de archivos, la caché de esquemas permanece en el disco local cuando se selecciona Notion; las anotaciones viven en Notion.

Cambiar de almacenamiento no copia lo que ya tienes — ejecuta export_annotations primero si quieres llevarlo contigo.

Actualización desde 0.3.x

list_entities y describe_entity se sustituyen por list_tables y describe_table, que leen la nueva caché e incorporan anotaciones y avisos de desviación. El directorio de caché de 0.3.x ~/.dataverse-mcp/cache/<host>/ ya no se lee y puede eliminarse; la nueva caché se reconstruye sola en la primera conexión. Tu caché de tokens no se toca, así que no hace falta volver a iniciar sesión.

Especificación de compilación (para colaboradores)

Objetivo

Compilar un servidor MCP independiente que hable directamente con la API web de Dataverse. Ir directo a la API web mantiene el servidor pequeño y con pocas dependencias, y permite usar el flujo de inicio de sesión que funciona de forma más amplia en máquinas y entornos — incluidos entornos con políticas de Acceso condicional estrictas. TypeScript, host local de Node, sin necesidad de registrar una nueva aplicación.

Por qué este enfoque de autenticación

Este servidor usa el mismo patrón de autenticación probado que XrmToolBox y los ejemplos de herramientas XRM de Microsoft: un cliente público previamente consentido proporcionado por Microsoft con redirección de bucle local, impulsado por un flujo estándar de MSAL de código de autorización más PKCE. Es el inicio de sesión de navegador ordinario en el que tu inquilino ya confía — funciona en todos los sistemas operativos, satisface las políticas de Acceso condicional que bloquean los flujos de código de dispositivo, y no necesita un intermediario a nivel de sistema operativo. Allá donde se conecta XrmToolBox, se conecta este servidor.

Client ID: 51f81489-12ee-4a9e-aaae-a2591f45987d
Redirect URI: http://localhost
Authority: https://login.microsoftonline.com/common
Scope: <environmentUrl>/.default

Esta es una aplicación de ejemplo multiinquilino de Microsoft con permiso delegado user_impersonation, sin necesidad de consentimiento de administrador. Si XrmToolBox ya se conecta correctamente en tu inquilino, este mismo identificador de cliente ya está demostrado para superar el Acceso condicional allí.

Objetivos no incluidos en v1

• Sin registro de aplicación personalizado en Entra (usa el identificador de cliente conocido de arriba)

• Sin principal de servicio / autenticación de CI (solo autenticación interactiva de usuario)

Estructura del repositorio

packages/
  core/                    @dataverse-platform/core — shared library, private
    src/
      index.ts             public surface
      auth.ts              MSAL interactive + silent acquisition
      cache.ts             atomic read/write helpers
      paths.ts             ~/.dataverse-mcp layout
      environment.ts       per-environment config, OrganizationId resolution
      dataverseClient.ts   Web API calls
      writes.ts            preview/confirm, validation, single-record resolution
      promotion.ts         annotation -> Dataverse description, maker mode only
      errors.ts            Dataverse error translation
      store.ts             $metadata + saved-view warm cache
      metadata/            schema cache: types, fingerprint, build, sampling
      annotations/         markdown model, store, drift detection
      storage/             backends: directory/git presets, Notion
  mcp-server/              dataverse-local-mcp — published to npm
    src/
      server.ts            MCP wiring
      tools/               tool definitions and formatters
    build.mjs              esbuild bundle (inlines core)
    prepack.mjs            stages README/LICENSE for packing
package.json               npm workspaces root
tsconfig.base.json

Las herramientas de evaluación (powerpreflight, velocity) se incorporan como más packages/*, llamando a core directamente como biblioteca en lugar de pasar por el servidor MCP.

Dependencias

npm install          # installs every workspace
npm run typecheck    # tsc -b across packages
npm run build        # core via tsc, mcp-server bundled via esbuild
npm run clean        # removes dist and tsbuildinfo

Las dependencias en tiempo de ejecución son @azure/msal-node, @modelcontextprotocol/sdk y open. Las llamadas HTTP usan el fetch global integrado de Node (de ahí el requisito de Node ≥ 18) — sin dependencia de cliente HTTP.

Paso 1 — Módulo de autenticación (src/auth.ts)

Adquiere y almacena en caché un token usando acquireTokenInteractive, que pone en marcha su propio listener de bucle local, sin necesidad de servidor HTTP manual.

• Identificador de cliente 51f81489-12ee-4a9e-aaae-a2591f45987d, autoridad https://login.microsoftonline.com/common

• Ámbito <environmentUrl>/.default

• Caché de tokens persistida en ~/.dataverse-mcp/token-cache.json

• Adquisición silenciosa desde la caché primero, con respaldo interactivo (se abre el navegador del sistema mediante el paquete open; configura DATAVERSE_MCP_NO_OPEN=1 para imprimir la URL en su lugar)

• El inicio de sesión interactivo siempre muestra el selector de cuentas (prompt: select_account) para que el inicio de sesión único del navegador no devuelva silenciosamente el token de la cuenta equivocada

• Los inicios de sesión interactivos concurrentes se deduplican por entorno — las peticiones en paralelo comparten una única ventana de navegador

• Un modo silentOnly respalda la precarga de la caché: lanza una excepción en lugar de abrir el navegador, de modo que el trabajo en segundo plano nunca interrumpe el arranque del cliente

Paso 2 — Cliente de la API web de Dataverse (src/dataverseClient.ts)

Capa fina sobre la API web de Dataverse (/api/data/v9.2/) que envía las cabeceras Authorization: Bearer, OData-MaxVersion: 4.0, OData-Version: 4.0, reintenta 429/503 según Retry-After para que una compilación masiva de metadatos sobreviva a los límites de protección del servicio. Cubre whoAmI(), get() genérico, creación/actualización/eliminación de registros (PATCH envía If-Match: * para que las actualizaciones nunca hagan un upsert silencioso), consultas FetchXML, vistas guardadas (savedquery + userquery, siguiendo @odata.nextLink), el EDMX sin procesar de $metadata, y lecturas de metadatos sobre EntityDefinitions.

Dos restricciones de Dataverse condicionan las llamadas de metadatos: EntityDefinitions rechaza $top y $orderby (acepta $select y $filter), y DisplayName/Description/RequiredLevel llegan como objetos en lugar de escalares, así que las etiquetas se extraen de UserLocalizedLabel.Label. Los conjuntos de opciones necesitan una conversión de tipo — el cliente intenta primero la conversión base EnumAttributeMetadata (una sola llamada para picklist, state, status y multiselect) y recurre a las conversiones concretas donde no se admite.

Paso 3 — Entrada del servidor MCP (src/server.ts)

Registra las herramientas enumeradas en la sección Herramientas de arriba, más el recurso dataverse://metadata, y pone en marcha la precarga de la caché en segundo plano después de que el transporte se conecte. Usa la clase Server estándar de @modelcontextprotocol/sdk con transporte stdio, igual que @microsoft/dataverse mcp mismo. La URL del entorno se pasa como primer argumento de la línea de comandos.

Paso 4 — Primera prueba

npm run build
node dist/server.js https://yourorg.crm.dynamics.com

Resultado esperado: el navegador del sistema se abre una vez para el inicio de sesión interactivo, el token se guarda en ~/.dataverse-mcp/token-cache.json, y las ejecuciones posteriores reutilizan el token en caché de forma silenciosa. Confirma el éxito llamando a la herramienta whoami y comprobando el UserId/BusinessUnitId devueltos. Tras el primer inicio de sesión, la precarga en segundo plano rellena ~/.dataverse-mcp/cache/<org-host>/ con metadata.xml, entities.json y saved-queries.json; los arranques posteriores sirven las herramientas de metadatos y vistas guardadas desde esa caché.

Paso 5 — Configuración de Claude Desktop

{
  "mcpServers": {
    "dataverse": {
      "command": "node",
      "args": ["/full/path/to/DataVerseLocalMCP/dist/server.js", "https://yourorg.crm.dynamics.com"]
    }
  }
}