01Conectar
Una URL. Sin SDK, sin puente stdio, sin registro previo.
El servidor habla HTTP directo. No hay que instalar nada, no hay SDK propio y no hace falta
un puente stdio.
Cliente MCP con transporte HTTP
Configuración mínimajson
{
"mcpServers": {
"entia": {
"url": "https://mcp.entia.systems/mcp"
}
}
}Sin credencial funcionan 6 de las 12 herramientas, tres de ellas con la
respuesta reducida. Para abrir el resto, añade la cabecera:
Con clavejson
{
"mcpServers": {
"entia": {
"url": "https://mcp.entia.systems/mcp",
"headers": {
"X-ENTIA-Key": "TU_CLAVE"
}
}
}
}Sin cliente: JSON-RPC a pelo
Listar las herramientasshell
curl -s -X POST https://mcp.entia.systems/mcp \
-H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'Fuente de verdadOrden de autoridad: tools/list en producción define el catálogo y los esquemas; services/mcp-ts/src/index.js define el runtime; core/mcp/plans.py define gating, cuotas y tiers; esta página es una representación generada. Si existe una discrepancia, la documentación no gana al runtime.
El saludo inicial
Peticiónjson-rpc
{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2024-11-05",
"capabilities": {},
"clientInfo": {
"name": "mi-cliente",
"version": "1.0"
}
}
}Respuesta REAL medida el 2026-08-27json-rpc
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"protocolVersion": "2024-11-05",
"capabilities": {
"tools": {
"listChanged": false
},
"resources": {
"listChanged": false,
"subscribe": false
},
"prompts": {
"listChanged": false
}
},
"serverInfo": {
"name": "entia-mcp-ts",
"version": "1.1.2-worker"
}
}
}Detalle del handshakeEl servidor no negocia la revisión del protocolo: responde siempre 2024-11-05, aunque pidas otra. Si tu cliente exige una revisión posterior, tenlo en cuenta antes de integrarlo.
02Protocolo
Qué métodos existen, qué devuelven y qué no está implementado.
Transporte HTTP con JSON-RPC 2.0 en el cuerpo. No hay SSE, no hay sesiones y no se emite
mcp-session-id: cada petición se basta a sí misma. Se aceptan lotes (un array de
peticiones); un lote formado solo por notificaciones responde 202 sin cuerpo.
| Método | Estado | Qué hace |
|---|
initialize | sí | Devuelve versión de protocolo, capacidades y datos del servidor. |
notifications/initialized | sí | Se acepta y se ignora, como manda la especificación. |
ping | sí | Comprobación de vida. |
tools/list | sí | Las 12 herramientas con su esquema de entrada y de salida. |
tools/call | sí | Invoca una herramienta. |
resources/list | sí, vacío | Devuelve []. Se implementa para no romper clientes estrictos. |
resources/templates/list | sí, vacío | Devuelve []. |
prompts/list | sí, vacío | Devuelve []. |
resources/read, prompts/get, sampling/createMessage, completion/complete | no | Fuera del alcance: la superficie de ENTIA es solo herramientas. |
Por qué están vacías y no ausentesLas capacidades resources y prompts se declaran y se sirven vacías a propósito. Declarar una capacidad y luego devolver -32601 al método correspondiente rompe a los clientes que confían en el saludo inicial, y es motivo de rechazo en las revisiones de directorio de conectores.
Forma de la respuesta
Toda herramienta devuelve el mismo envoltorio: un bloque de texto con el JSON serializado y,
además, structuredContent con el mismo objeto ya parseado —las 12 declaran
esquema de salida—. Si algo falla dentro de la herramienta, el envoltorio llega con
isError: true y el detalle dentro del texto.
Envoltorio de tools/calljson-rpc
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [ { "type": "text", "text": "{ ...el JSON de la herramienta... }" } ],
"structuredContent": { "...el mismo objeto, ya parseado..." },
"isError": false
}
}El bloque _meta
Casi todas las respuestas traen un _meta con la trazabilidad de esa llamada.
| Campo | Qué significa |
|---|
cache_status | miss, kv_hit, static, kv_mcp_tool_cache. Dice de dónde salió la respuesta. |
fast_path_used | Si se resolvió por el camino rápido sin tocar el origen. |
latency_ms | Milisegundos del cálculo. Si la respuesta es cacheada, es la latencia del cálculo original, no la de tu llamada. |
phase_timings | Desglose por fase cuando la herramienta orquesta varias fuentes. |
sources / source | Las fuentes públicas empleadas, nombradas. |
_unverified | Los campos que el servidor no puede acreditar y por eso devuelve nulos. |
_cache_hit · _cached_at · _cache_ttl | Presentes en las herramientas con caché de servidor. Te dicen de cuándo es el documento. |
Latencia fósilUn latency_ms alto junto a _cache_hit: true no significa que el servicio vaya lento: significa que ese documento tardó eso en construirse cuando se construyó. Medido en get_full_dossier: latency_ms: 3022 en una respuesta servida desde caché en milisegundos. Para medir latencia de servicio, mídela en tu cliente.
03Autenticación
Clave de API u OAuth 2.1 con registro dinámico. Y qué pasa si no mandas nada.
Dos esquemas, ambos vivos. Elige uno.
1 · Clave de API
Cabecerahttp
X-ENTIA-Key: TU_CLAVE
# equivalente exacto:
Authorization: Bearer TU_CLAVE
Si mandas las dos, gana Authorization. Se consigue una clave gratuita de nivel
TRACE por correo, sin tarjeta:
Alta de clave TRACEshell
curl -s -X POST https://api.entia.systems/api/v1/mcp/register \
-H 'Content-Type: application/json' \
-d '{"email":"tu@empresa.com"}'2 · OAuth 2.1 con registro dinámico de cliente
El propio servidor es su autoridad de autorización. Un cliente MCP remoto puede darse de alta
solo, sin que nadie le entregue credenciales por otro canal.
| Metadato | Valor |
|---|
| Descubrimiento del recurso | /.well-known/oauth-protected-resource/mcp |
| Descubrimiento del emisor | /.well-known/oauth-authorization-server |
| Registro dinámico | POST /oauth/register (RFC 7591, abierto) |
| Autorización | GET /oauth/authorize |
| Token | POST /oauth/token |
| Concesiones | authorization_code, refresh_token, client_credentials |
| PKCE | S256, obligatorio |
| Ámbito | mcp (único) |
| Vida del token | 30 días (código de autorización) · 24 h (credenciales de cliente) · 90 días el de refresco |
Cómo funciona por dentroLos tokens son sobres sellados que envuelven una clave de ENTIA: no hay almacén de sesiones en el servidor. Un token vale exactamente lo que valga la clave que lleva dentro.
Sin credencial
6 de las 12 herramientas responden sin clave. Tres de ellas
—entity_lookup, search_entities y verify_vat— devuelven una
vista reducida: el servidor recorta la respuesta y lo declara con
access_level, la lista gated_fields y
_meta.redacted_for_anon: true. No es un fallo silencioso; la propia respuesta te dice
qué falta y qué lo abre.
Límites de frecuencia
| Llamante | Límite |
|---|
| Anónimo | 10 peticiones por minuto |
| Con credencial | 60 peticiones por minuto |
run_risk_audit | 5 por minuto, por ser una auditoría de red en vivo |
Lo que NO vas a recibirEl servidor MCP no devuelve cabeceras X-RateLimit-* ni RateLimit-*, y tampoco Retry-After. Verificado sobre respuestas reales el 2026-08-27. Si tu cliente las espera para autolimitarse, no las va a encontrar: limita por tu lado a partir de los números de la tabla.
05Errores
Dos niveles: protocolo y herramienta. Confundirlos es el primer error de integración.
Hay dos niveles y conviene no confundirlos. Los errores de protocolo viajan en
el campo error de JSON-RPC. Los errores de herramienta viajan como un
resultado correcto con isError: true y un JSON dentro del texto — así lo prescribe la
especificación de MCP, para que el modelo pueda leer el error y corregirse.
| Código | Nivel | Cuándo | HTTP |
|---|
-32700 | protocolo | JSON mal formado. | HTTP 200 |
-32600 | protocolo | La petición no es JSON-RPC válido. | HTTP 200 |
-32601 | protocolo | Método desconocido. | HTTP 200 |
-32602 | protocolo | Herramienta desconocida, o argumentos inválidos. El campo data trae errors[], el inputSchema completo y un enlace a esta página. | HTTP 200 |
API key required | herramienta | Falta credencial en una herramienta que la exige. El cuerpo trae required_tier y checkout_url. | HTTP 401 + WWW-Authenticate |
tier_restricted | herramienta | Credencial válida, pero de un plan que no abre esa herramienta. | HTTP 200 |
dpa_required | herramienta | La herramienta trata datos personales y exige acuerdo de encargo firmado. | HTTP 403, sin reto de autenticación |
tier_verification_unavailable | herramienta | No se pudo confirmar el plan de la clave contra el origen. Se cierra en falso: deniega. | HTTP 200 |
Un error de validación se puede corregir sin salir del protocolo
Error REAL medido el 2026-08-27json-rpc
{
"jsonrpc": "2.0",
"id": 8,
"error": {
"code": -32602,
"message": "Invalid arguments for 'search_entities': missing required argument 'q'",
"data": {
"tool": "search_entities",
"errors": [
"missing required argument 'q'"
],
"inputSchema": {
"...": "el esquema completo, tal cual"
},
"docs": "https://entia.systems/mcp-docs"
}
}
}El servidor devuelve el esquema entero en el propio error. Un agente puede releerlo y reintentar
sin que nadie le pase documentación por fuera.
El reto de autenticación
Cabecera REAL medida el 2026-08-27http
HTTP/2 401
www-authenticate: Bearer error="invalid_token",
error_description="Authentication required for this tool",
resource_metadata="https://mcp.entia.systems/.well-known/oauth-protected-resource/mcp",
scope="mcp"
La combinación es deliberada: el 401 en el transporte es lo que hace que un
cliente MCP descubra el servidor de autorización y arranque el flujo de OAuth; el
402 dentro del cuerpo es lo que le dice a un humano qué plan abre esa herramienta.
Sin el 401, ningún cliente encontraría la metadata; sin el cuerpo, nadie sabría el precio.
Limitación conocida, medida y declaradaHoy una credencial inválida —una clave mal escrita, caducada o revocada— no se distingue de un fallo transitorio: la respuesta es tier_verification_unavailable con retry_after_seconds: 5, y un token OAuth inválido se degrada a llamante anónimo sin emitir reto. Un cliente con reintento automático puede quedarse en bucle contra un error que nunca se va a curar.
Recomendación mientras esto se corrige: trata tier_verification_unavailable como un posible problema de credencial, limita los reintentos a dos y comprueba la clave antes de insistir. Las herramientas abiertas siguen respondiendo con normalidad aunque la clave sea inválida.
06Planes y cuotas
Volumen y capacidad. Los planes se diferencian en las dos cosas.
La cuota se cuenta en entidades consultadas: cada llamada a una herramienta
descuenta una. Los planes se diferencian en dos cosas a la vez, y conviene no confundirlas: cuánto
volumen tienes y qué herramientas se te abren.
| Plan | Precio | Entidades/mes | Al superarlo | Herramientas |
|---|
| TRACE | gratis | 100 | bloqueo | 6 de 12 |
| EDGE | 9,90 €/mes | 10.000 | 0,01 €/llamada | 3 de 12 |
| SIGNAL | 29 €/mes | 500 | bloqueo | 9 de 12 |
| BUILD | 99 €/mes | 2.500 | bloqueo | 10 de 12 |
| INTEGRATE | 399 €/mes | 10.000 | 0,15 €/llamada | 11 de 12 |
| OPERATE | 1.499 €/mes | 100.000 | 0,10 €/llamada | 11 de 12 |
| SCALE · ENTERPRISE | contratado | contratado | contratado | hasta 12 de 12 |
Qué abre cada plan, herramienta por herramienta
| Herramienta | Acceso mínimo | Grupo |
|---|
entity_lookup | Abierta | Identidad y verificación |
search_entities | Abierta | Identidad y verificación |
verify_vat | Abierta | Identidad y verificación |
get_full_dossier | INTEGRATE+ | Identidad y verificación |
zone_profile | SIGNAL+ | Contexto y mercado |
get_competitors | BUILD+ | Contexto y mercado |
run_risk_audit | SIGNAL+ | Contexto y mercado |
get_entia_home | Abierta | Corpus publicado |
get_entity_home_projection | SIGNAL+ | Corpus publicado |
get_showcase | Abierta | Descubrimiento y plataforma |
get_platform_stats | Abierta | Descubrimiento y plataforma |
professional_lookup | Enterprise + DPA | Datos personales, bajo contrato |
Cómo se calcula esta tabla6 de las 12 herramientas están abiertas y 6 se abren por plan. Esta tabla se calcula cruzando el minTier que cada herramienta declara en el servidor con el mapa de planes del gateway: son dos ficheros distintos y el generador de esta página aborta si dejan de decir lo mismo.
Comprar
Las dos rutas realesshell
# Alta gratuita TRACE (sin tarjeta)
curl -s -X POST https://api.entia.systems/api/v1/mcp/register \
-H 'Content-Type: application/json' -d '{"email":"tu@empresa.com"}'
# Checkout de un plan de pago -> redirige a Stripe
curl -sI 'https://api.entia.systems/api/v1/mcp/checkout?tier=signal'Tras el pago, la clave se revela en /mcp-dashboard.
SCALE y ENTERPRISE no tienen checkout público: se contratan en
fv@entia.systems.
07Procedencia y límites
De dónde sale cada dato y qué es exactamente lo que ENTIA no afirma.
El MCP es una proyección operativa del grafo canónico de identidad económica de ENTIA.
Cada respuesta debe poder distinguir dato observado, resolución de entidad, procedencia,
estado de verificación y limitaciones. Una Entia Home, la API y MCP son superficies de consumo
del mismo activo gobernado; no sustituyen a la fuente ni convierten una inferencia en hecho.
Estados de verificación
| Estado | Qué significa |
|---|
VERIFIED | Confirmado contra una fuente registral independiente. |
FOUND | Localizado en el corpus, sin corroboración independiente todavía. |
not_found | Se consultó la fuente y no está. Es un resultado, no un error. |
not_run | No se consultó esa fuente en esta llamada. Distinto de no encontrar. |
PARTIAL | Insignia agregada: hay corroboración, pero no en todos los ejes. |
disclosure_restricted | La fuente existe y responde, pero el Estado miembro no divulga ese campo. |
La diferencia entre not_found y not_run es la que separa una respuesta
auditable de una conjetura, y por eso viaja en el payload.
Un valor que no se puede servir se declara
Fragmento REAL de zone_profile, medido el 2026-08-27json
"ratio_paro_vs_declaraciones_pct": {
"value": null,
"comparable": false,
"warning": "source_value_out_of_percent_range_not_served",
"raw_value": 1895.2
}Una ratio del 1.895 % no es un porcentaje: es la señal de que numerador y denominador no
comparten ámbito geográfico. El servidor podría redondear y entregar algo presentable. Entrega el
problema.
Lo que ENTIA NO afirma
El sello de integridad: qué es y qué no esAlgunas respuestas incluyen un sello de integridad calculado sobre el cuerpo de la respuesta. Conviene entender exactamente qué es, porque es fácil leerlo por lo que no es.
Es un código de autenticación de mensaje simétrico, calculado con un secreto que solo tiene ENTIA. Sirve para detectar que una respuesta emitida por ENTIA ha sido modificada, y solo ENTIA puede verificarlo. Al ser simétrico, no distingue emisor de verificador: no prueba el origen frente a un tercero.
No es una firma electrónica. No es un sello electrónico. No es un sello de tiempo. PrecisionAI Marketing OU no es prestador cualificado de servicios de confianza y no figura en ninguna lista de confianza de la Unión Europea. Nada de lo que devuelve esta API constituye por sí mismo prueba oponible frente a terceros. Si tu caso de uso necesita efectos jurídicos cualificados, escríbenos antes de integrar en vez de deducirlo de un campo.
Tamaño y cobertura del corpus
Esta documentación no publica una cifra operacional congelada. El estado actual se obtiene desde get_platform_stats, de modo que integraciones y documentación consultan la misma superficie de runtime:
Estado actual, reproducibleshell
curl -s -X POST https://mcp.entia.systems/mcp \
-H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_platform_stats","arguments":{}}}'No duplicar métricasLas cifras que aparecen dentro de respuestas de ejemplo son snapshots fechados, no constantes del producto. Para cobertura actual, países, fuentes o tamaño de corpus, consulta get_platform_stats en el momento de uso.
08Versionado y retiradas
Qué rompe, qué no, y dónde siguen vivas las herramientas retiradas.
Una herramienta retirada no es una herramienta borrada. Se retira de la superficie pública
cuando deja de cumplir el criterio de que todo lo listado responde correctamente con
parámetros válidos; el dato sigue accesible por otro camino.
| Herramienta | Retirada | Por qué | Dónde sigue viva |
|---|
ai_ready_profile | 2026-08-17 | roadmap_status_fails_directory_review | /api/v1/v3/ai_ready_profile |
borme_lookup | 2026-06-15 | El enlace sintético por CIF no era fiable en la cola larga: BORME no publica el CIF. | Vía entity_lookup y get_full_dossier |
lookup_by_domain | 2026-07-23 | Retirada de la superficie pública. | Vía entity_lookup |
Qué se considera un cambio que rompe
| Cambio | ¿Rompe? |
|---|
| Añadir una herramienta | No |
| Añadir un campo a una respuesta | No. Ignora los campos que no conozcas. |
| Añadir un parámetro opcional | No |
Añadir un alias de sector al enum | No |
| Quitar o renombrar un campo | Sí |
| Hacer requerido un parámetro que era opcional | Sí |
| Retirar una herramienta | Sí, y se anuncia en esta tabla |
| Cambiar el tier mínimo de una herramienta | Sí para quien esté por debajo |
La versión del servidor viaja en cada saludo: serverInfo.version. Hoy,
1.1.2-worker.
09Seguridad
Solo lectura, datos personales bajo contrato y postura ante inyección por herramientas.
Todas las herramientas son de solo lectura
Las 12 declaran readOnlyHint: true, destructiveHint: false e
idempotentHint: true. Ninguna escribe, ninguna borra y ninguna dispara efectos en
sistemas de terceros. Un agente puede invocarlas sin permiso de escritura.
Datos personales
El servidor trata personas jurídicas. La única excepción es
professional_lookup, que verifica colegiación de personas físicas y por eso exige tier
Enterprise y acuerdo de encargo de tratamiento firmado. Su respuesta va minimizada por
diseño: se eliminan nombre y apellidos antes de responder, y la minimización se declara en el
propio payload.
Inyección a través de herramientas
El contenido que devuelven las herramientas procede de registros públicos y de páginas de
terceros —por ejemplo el análisis de un dominio en run_risk_audit—. Trátalo como
datos, nunca como instrucciones. Si tu agente encadena esa salida hacia acciones
con efectos, ponle una barrera de confirmación en medio: es la práctica correcta con cualquier
servidor MCP, incluido este.
Residencia y responsable
Operado por PrecisionAI Marketing OÜ, Sepapaja tn 4, 11415 Tallin, Estonia.
Código de registro mercantil 17048063. Infraestructura en la Unión Europea.
10Preguntas
¿Necesito una clave para empezar?
No. 6 de las 12 herramientas responden sin credencial, tres de ellas con la respuesta reducida y declarándolo. La clave TRACE es gratuita y se pide por correo desde la API.
¿Qué revisión del protocolo MCP sirve el servidor?
2024-11-05. El servidor no negocia: responde esa revisión aunque el cliente pida otra.
¿Por qué recibo un 401 si mi cliente no usa OAuth?
Porque el 401 con WWW-Authenticate es lo que permite a un cliente MCP descubrir el servidor de autorización. Si usas clave de API, basta con añadir la cabecera X-ENTIA-Key y el 401 desaparece.
¿Cuántos campos devuelve get_full_dossier?
Depende de la entidad. El propio documento trae _meta.fields_populated con el recuento de esa respuesta. Cualquier cifra fija que veas por ahí es una foto de una entidad concreta, no una constante.
¿La caché me puede devolver un dato viejo?
Sí, y te lo dice. Las herramientas con caché de servidor traen _cached_at y _cache_ttl. La más larga es get_full_dossier, con siete días.
¿Se puede usar el corpus para entrenar modelos?
No bajo estos planes. El acceso por API y MCP es para consulta en tiempo de inferencia. La minería de textos y datos y el entrenamiento requieren licencia aparte: tdm-policy.json.
Si un modelo no puede verificar a una empresa, no la va a recomendar.
Conectar cuesta una línea de configuración, y las herramientas abiertas
responden ahora mismo, sin registro.