Notas prácticas: Herramientas MCP dentro de las aplicaciones empresariales: Amigable para principiantes

Las notas siguientes reconstruyen un camino práctico para abordar “MCP Tools Inside Enterprise Applications: A Beginner-Friendly Deep Dive”. Se da énfasis en los contratos, las verificaciones y los marcadores de posición para código, en lugar de en un enfoque motivacional. Al trabajar en la etapa de descripción general, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de un fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Considere esta etapa como un contrato entre las entradas y los resultados validados. Asigne nombres a los elementos generados, defina las verificaciones de éxito y evite completaciones parciales silenciosas.

1. El problema: Por qué las empresas necesitaron MCP en primer lugar

El problema radica en que la etapa inicial funciona mejor cuando se trata como una superficie medible. Capture un registro ejemplar, un caso de fallo y la nota de reversión antes de ampliar el alcance. Registre los tiempos y el costo de tokens o consultas junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando el proceso pasa de la fase de demostración a entornos compartidos. Exponga herramientas con esquemas limitados y etiquetas claras sobre efectos secundarios. Los administradores necesitan saber qué llamadas modifican el estado antes de aprobarlas automáticamente.

BEFORE MCP — the N x M integration problem

  ┌───────────┐        ┌─────────────┐
  │  Agent A  │───────▶│  CRM API    │  (custom connector #1)
  └───────────┘        └─────────────┘
  ┌───────────┐        ┌─────────────┐
  │  Agent A  │───────▶│  Ticketing  │  (custom connector #2)
  └───────────┘        └─────────────┘
  ┌───────────┐        ┌─────────────┐
  │  Agent B  │───────▶│  CRM API    │  (custom connector #3 -
  └───────────┘        └─────────────┘   yes, AGAIN, for a different agent)
  ┌───────────┐        ┌─────────────┐
  │  Agent B  │───────▶│  Data       │  (custom connector #4)
  └───────────┘        │  Warehouse  │
                       └─────────────┘
  N agents x M systems = N x M custom, non-reusable integrations.
  Every new agent re-implements auth, retries, schemas, error handling.

AFTER MCP — one protocol, many servers, many clients

  ┌───────────┐                          ┌───────────────────┐
  │  Agent A  │──┐                   ┌─▶│  MCP Server: CRM   │
  └───────────┘  │    ┌───────────┐  │   └───────────────────┘
                 ├───▶│    MCP   │───┤  ┌───────────────────┐
  ┌───────────┐  │    │  (shared  │  ├─▶│ MCP Server: Ticket │
  │  Agent B  │──┘    │  protocol)│  │   └───────────────────┘
  └───────────┘       └───────────┘  │  ┌──────────────────┐
                                     └─▶│ MCP Server: DW   │
                                        └──────────────────┘
  Any MCP-compatible agent can now talk to any MCP server.
  Build the connector once, reuse it everywhere.

2. Conceptos básicos, explicados de forma sencilla

La etapa de “Explicación de los 2 conceptos clave” funciona mejor cuando se trata como una superficie medible. Capture un registro de éxito ejemplar, un caso de fallo y la nota de reversión antes de ampliar el alcance. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el sistema. Exponga herramientas con esquemas limitados y etiquetas explícitas sobre efectos secundarios. Los administradores necesitan saber qué llamadas modifican el estado antes de aprobarlas automáticamente.

Las tres primitivas que puede exponer un servidor

Las tres primitivas de una etapa funcionan mejor cuando se tratan como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Documente tanto el camino óptimo como el de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Exponga herramientas con esquemas limitados y etiquetas explícitas de efectos secundarios. Los administradores necesitan saber qué llamadas modifican el estado antes de aprobarlas automáticamente. Las tres primitivas de una etapa funcionan mejor cuando se tratan como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Trate esta etapa como un contrato entre las entradas y las salidas validadas. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace las completaciones parciales silenciosas.

3. La arquitectura, las tres capas juntas

En la etapa 3 de Arquitectura General, defina las entradas, el responsable de cada paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Registre los tiempos de ejecución y el costo de los tokens o consultas junto con los resultados funcionales. La visibilidad temprana del costo evita facturas inesperadas cuando el flujo pasa de entornos de demostración a entornos compartidos. Autentíquese en la pasarela y vuelva a autorizarse en el plano de datos. Un token portador por sí solo no constituye un límite entre tenencias.

┌─────────────────────────── HOST APPLICATION ───────────────────────────┐
│   e.g. an internal AI assistant, IDE plugin, support copilot           │
│                                                                        │
│   ┌───────────────┐        ┌───────────────┐       ┌───────────────┐   │
│   │  MCP Client 1 │        │  MCP Client 2 │       │  MCP Client 3 │   │
│   └───────┬───────┘        └───────┬───────┘       └───────┬───────┘   │
└───────────┼────────────────────────┼───────────────────────┼───────────┘
            │ JSON-RPC over          │ JSON-RPC over         │ JSON-RPC over
            │ stdio / HTTPS          │ stdio / HTTPS         │ stdio / HTTPS
            ▼                        ▼                       ▼
   ┌──────────────────┐     ┌──────────────────┐     ┌─────────────────┐
   │   MCP Server     │     │   MCP Server     │     │   MCP Server    │
   │  wraps HR system │     │  wraps Ticketing │     │  wraps Data     │
   │  (tools: lookup, │     │  (tools: create, │     │  Warehouse      │
   │   update)        │     │   status, close) │     │  (tools: query) │
   └──────────────────┘     └──────────────────┘     └─────────────────┘

4. Creación de su primer servidor MCP (Node.js / TypeScript)

En la fase 4 “Construyendo el primero”, defina las entradas, el responsable de cada paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Guarde la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben encontrarse en un lugar donde los operadores puedan auditarlos sin necesidad de leer todo el sistema. Autentique en la pasarela y vuelva a autorizarlo en el plano de datos. Un token portador por sí solo no constituye un límite entre tenencias.

4.1 Configuración del proyecto

En la fase de configuración del Proyecto 4 1, defina las entradas, el responsable de la tarea y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar la tarea a partir de un punto de control conocido sin tener que adivinar el estado oculto. Documente tanto la ruta óptima como la ruta de recuperación. Las intentonas, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Autentique en la pasarela y vuelva a autorizarlo en el plano de datos. Un token portador por sí solo no constituye un límite entre tenencias.

mkdir helpdesk-mcp-server && cd helpdesk-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript tsx @types/node
npx tsc --init

En la fase de configuración del Proyecto 4 1, defina las entradas, el responsable de la tarea y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar la tarea a partir de un punto de control conocido sin tener que adivinar el estado oculto. Considere esta fase como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina comprobaciones de éxito y rechace las completaciones parciales silenciosas.

4.2 El código del servidor

Al trabajar en la fase 4.2 del servidor, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Registre los tiempos y el costo de tokens o consultas junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando se pasa de entornos de demostración a entornos compartidos. Registre el nombre de la herramienta, el hash de los argumentos, la latencia y el resultado de cada llamada. Depurar bucles sin ese registro desperdicia horas.

// src/server.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

// --- A stand-in for a real internal ticketing API client ---
// In a real enterprise server this would call your ITSM system
// (ServiceNow, Jira Service Management, Zendesk, an internal API, etc.)
const ticketStore = new Map<string, { status: string; subject: string }>();
let nextId = 1000;
// 1. Create the server instance.
//    "name" and "version" identify this server to any client that connects.
const server = new McpServer({
  name: "helpdesk-mcp-server",
  version: "1.0.0",
});
// 2. Register a tool: create_support_ticket
server.registerTool(
  "create_support_ticket",
  {
    title: "Create Support Ticket",
    description:
      "Creates a new IT helpdesk ticket for the requesting employee.",
    inputSchema: {
      subject: z.string().describe("Short summary of the issue"),
      priority: z.enum(["low", "medium", "high", "urgent"]),
      employeeId: z.string().describe("Requesting employee's ID"),
    },
    outputSchema: {
      ticketId: z.string(),
      status: z.string(),
    },
  },
  async ({ subject, priority, employeeId }) => {
    const ticketId = `TCK-${nextId++}`;
    ticketStore.set(ticketId, { status: "open", subject });
    const output = { ticketId, status: "open" };
    // MCP tool results return a "content" array (what a human/LLM reads)
    // and, optionally, "structuredContent" (typed data other code can use).
    return {
      content: [
        {
          type: "text",
          text: `Created ticket ${ticketId} (priority: ${priority}) for employee ${employeeId}.`,
        },
      ],
      structuredContent: output,
    };
  }
);
// 3. Register a second tool: get_ticket_status
server.registerTool(
  "get_ticket_status",
  {
    title: "Get Ticket Status",
    description: "Looks up the current status of an existing support ticket.",
    inputSchema: {
      ticketId: z.string(),
    },
    outputSchema: {
      status: z.string(),
    },
  },
  async ({ ticketId }) => {
    const ticket = ticketStore.get(ticketId);
    if (!ticket) {
      // Returning isError lets the model know the call failed
      // WITHOUT crashing the whole conversation.
      return {
        content: [{ type: "text", text: `No ticket found with ID ${ticketId}.` }],
        isError: true,
      };
    }
    return {
      content: [{ type: "text", text: `Ticket ${ticketId} is currently "${ticket.status}".` }],
      structuredContent: { status: ticket.status },
    };
  }
);
// 4. Wire the server to a transport and start listening.
//    stdio is perfect for local development and desktop-hosted tools.
const transport = new StdioServerTransport();
await server.connect(transport);

4.3 Qué está sucediendo realmente aquí (teoría línea por línea)

Al trabajar en la fase 4 3 What’s, anote primero el contrato: los datos de entrada requeridos, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Guarde la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el sistema. Registre el nombre de la herramienta, el hash de los argumentos, la latencia y el resultado de cada llamada. Depurar agentes sin ese registro desperdicia horas.

4.4 Ejecutarlo

Al trabajar en la fase de “Ejecutarlo” del proceso 4 4, anote primero el contrato: los datos de entrada requeridos, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Documente tanto la ruta de éxito como la ruta de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras realizadas posteriormente. Registre el nombre de la herramienta, el hash de los argumentos, la latencia y el resultado de cada llamada. Depurar ciclos sin ese historial desperdicia horas.

npx tsx src/server.ts

Al trabajar en la fase de “Ejecutarlo” del proceso 4 4, anote primero el contrato: los datos de entrada requeridos, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Considere esta fase como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina comprobaciones de éxito y evite las completaciones parciales silenciosas.

5. Creación de un cliente MCP dentro de una aplicación empresarial

La etapa 5 de creación de MCP funciona mejor cuando se trata como una superficie medible. Capture una transcripción ejemplar, un caso de fallo y la nota de reversión antes de ampliar el alcance. Registre los tiempos y el costo del token o la consulta junto con los resultados funcionales. La visibilidad temprana de los costos evita facturas inesperadas cuando el proceso pasa de la demostración a entornos compartidos.

// src/client.ts
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

async function main() {
  // 1. Describe how to launch the server. Here we spawn it as a
  //    local subprocess - in production you'd more commonly point
  //    this at a remote HTTP-based server instead (see Section 6).
  const transport = new StdioClientTransport({
    command: "npx",
    args: ["tsx", "src/server.ts"],
  });
  // 2. Create a client and connect. This performs the MCP
  //    handshake and capability negotiation automatically.
  const client = new Client({ name: "internal-ai-assistant", version: "1.0.0" });
  await client.connect(transport);
  // 3. Discover what tools this server offers - this is the same
  //    mechanism an LLM uses to "learn" what it can do.
  const { tools } = await client.listTools();
  console.log("Available tools:", tools.map((t) => t.name));
  // 4. Call a tool, just like the LLM would.
  const result = await client.callTool({
    name: "create_support_ticket",
    arguments: {
      subject: "VPN keeps disconnecting",
      priority: "high",
      employeeId: "E-4821",
    },
  });
  console.log(result.content);
  await client.close();
}
main();

Por qué es importante conceptualmente

La etapa de “Por qué es importante conceptualmente” funciona mejor cuando se trata como una superficie medible. Capture un registro ejemplar, un caso de fallo y la nota de reversión antes de ampliar el alcance. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos confidenciales y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan realizar auditorías sin tener que leer todo el sistema.

6. De prototipo local a despliegue empresarial

La etapa “6 From Local Prototype” funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Documente tanto el camino óptimo como el de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son ajustes realizados posteriormente. Exponga herramientas con esquemas limitados y etiquetas explícitas de efectos secundarios. Los administradores necesitan saber qué llamadas modifican el estado antes de aprobarlas automáticamente. La etapa “6 From Local Prototype” funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Considere esta etapa como un contrato entre las entradas y las salidas validadas. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace las completaciones parciales silenciosas.

// src/httpServer.ts
import express from "express";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";

const app = express();
app.use(express.json());
app.post("/mcp", async (req, res) => {
  // In a real enterprise deployment, authentication middleware would
  // run BEFORE this point - verifying a bearer token, checking scopes,
  // and attaching the caller's identity to the request.
  const server = buildHelpdeskServer(); // same registerTool calls as before
  const transport = new StreamableHTTPServerTransport({
    sessionIdGenerator: undefined, // stateless mode: simplest to scale horizontally
  });
  res.on("close", () => transport.close());
  await server.connect(transport);
  await transport.handleRequest(req, res, req.body);
});
app.listen(3000, () => console.log("MCP server listening on :3000"));

7. Lista de verificación de consideraciones de nivel empresarial

En la fase de la lista de verificación de 7 consideraciones de nivel empresarial, defina las entradas, el responsable de cada paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Registre los tiempos de ejecución y el costo de los tokens o consultas junto con los resultados funcionales. La visibilidad temprana del costo evita facturas inesperadas cuando el proceso pasa de entornos de demostración a entornos compartidos. Autentíquese en la pasarela y vuelva a autorizarse en el plano de datos. Un token portador por sí solo no constituye un límite entre tenencias.

8. Donde se aplica esto en casos de uso reales empresariales

Para la etapa 8 “Where This Shows”, defina las entradas, el responsable de cada paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Guarde la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben encontrarse en un lugar que los operadores puedan auditar sin necesidad de leer todo el sistema.

9. Errores comunes que enfrentan los principiantes

En la etapa de los 9 errores comunes para principiantes, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso desde un punto de control conocido sin tener que adivinar el estado oculto. Documente tanto la ruta óptima como la ruta de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Autentique en la pasarela y vuelva a autorizar en el plano de datos. Un token portador por sí solo no constituye un límite entre tenencias. En la etapa de los 9 errores comunes para principiantes, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso desde un punto de control conocido sin tener que adivinar el estado oculto. Trate esta etapa como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace las completaciones parciales silenciosas.

10. Conclusión

Al trabajar en la etapa de 10 Resumen, anote primero el contrato: los datos necesarios, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Registre los tiempos y el costo en tokens o consultas junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando el proceso pasa de la fase de demostración a entornos compartidos. Registre el nombre de la herramienta, el hash de los argumentos, la latencia y el resultado de cada llamada. Depurar bucles sin ese historial desperdicia horas.

Lista de verificación operativa

En la etapa de Lista de verificación operativa, defina los datos de entrada, el responsable de cada paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto.

Preferir unidades pequeñas y verificables en lugar de scripts extensos. Cuando un paso falla, el error debe indicar una única responsabilidad y no un proceso complicado.

Autenticar en la pasarela y volver a autorizar en el plano de datos. Un token portador por sí solo no constituye un límite entre entidades distintas.

Escribir un manual breve: cómo rotar claves, cómo vaciar la cola y cómo revertir la última operación de ingreso.

Tratar esta etapa como un contrato entre las entradas y las salidas validadas. Nombrar los artefactos, definir las verificaciones de éxito y rechazar completaciones parciales silenciosas.

Autenticar en la pasarela y volver a autorizar en el plano de datos. Un token portador por sí solo no constituye un límite entre entidades distintas.

Antes de promocionar el conjunto de tecnologías, congele las versiones, capture una transcripción de referencia para la ruta crítica y confirme los pasos de reversión. Los entornos compartidos requieren límites de velocidad, verificaciones de tenencia y un responsable claro para la rotación de secretos. Prefiera una fiabilidad sencilla a demostraciones ingeniosas pero puntuales.

Nota para el lote 100916d5ed60: mantenga las claves del proveedor fuera del repositorio, establezca un límite para los tokens por sesión y almacene las transcripciones junto a los archivos de prueba para que los cambios posteriores en el modelo sigan siendo comparables.