Practical notes: MCP Tools Inside Enterprise Applications: A Beginner-Friendly

The following notes reconstruct a practical path around “MCP Tools Inside Enterprise Applications: A Beginner-Friendly Deep Dive”. Emphasis stays on contracts, checks, and drop-in code placeholders rather than motivational framing. When working through the Overview stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion.

1. The Problem: Why Enterprises Needed MCP in the First Place

The 1 The Problem Why stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Record timings and token or query cost next to functional results. Cost visibility early prevents surprise bills when the path moves from demo to shared environments. Expose tools with narrow schemas and explicit side-effect labels. Hosts need to know which calls mutate state before they auto-approve.

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. Core Concepts, Explained Simply

The 2 Core Concepts Explained stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph. Expose tools with narrow schemas and explicit side-effect labels. Hosts need to know which calls mutate state before they auto-approve.

The three primitives a server can expose

The The three primitives a stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Document the happy path and the recovery path together. Retries, human gates, and dead-letter handling are part of the product, not later polish. Expose tools with narrow schemas and explicit side-effect labels. Hosts need to know which calls mutate state before they auto-approve. The The three primitives a stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion.

3. The Architecture, All Three Layers Together

For the 3 The Architecture All stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Record timings and token or query cost next to functional results. Cost visibility early prevents surprise bills when the path moves from demo to shared environments. Authenticate at the gateway and re-authorize at the data plane. A bearer token alone is not a tenancy boundary.

┌─────────────────────────── 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. Building Your First MCP Server (Node.js / TypeScript)

For the 4 Building Your First stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph. Authenticate at the gateway and re-authorize at the data plane. A bearer token alone is not a tenancy boundary.

4.1 Project setup

For the 4 1 Project setup stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Document the happy path and the recovery path together. Retries, human gates, and dead-letter handling are part of the product, not later polish. Authenticate at the gateway and re-authorize at the data plane. A bearer token alone is not a tenancy boundary.

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

For the 4 1 Project setup stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion.

4.2 The server code

When working through the 4 2 The server stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Record timings and token or query cost next to functional results. Cost visibility early prevents surprise bills when the path moves from demo to shared environments. Log tool name, args hash, latency, and outcome for every call. Debugging agent loops without that trail wastes hours.

// 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 What’s actually happening here (line-by-line theory)

When working through the 4 3 What s stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph. Log tool name, args hash, latency, and outcome for every call. Debugging agent loops without that trail wastes hours.

4.4 Running it

When working through the 4 4 Running it stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Document the happy path and the recovery path together. Retries, human gates, and dead-letter handling are part of the product, not later polish. Log tool name, args hash, latency, and outcome for every call. Debugging agent loops without that trail wastes hours.

npx tsx src/server.ts

When working through the 4 4 Running it stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion.

5. Building an MCP Client Inside an Enterprise Application

The 5 Building an MCP stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Record timings and token or query cost next to functional results. Cost visibility early prevents surprise bills when the path moves from demo to shared environments. Expose tools with narrow schemas and explicit side-effect labels. Hosts need to know which calls mutate state before they auto-approve.

// 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();

Why this matters conceptually

The Why this matters conceptually stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph. Expose tools with narrow schemas and explicit side-effect labels. Hosts need to know which calls mutate state before they auto-approve.

6. From Local Prototype to Enterprise Deployment

The 6 From Local Prototype stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Document the happy path and the recovery path together. Retries, human gates, and dead-letter handling are part of the product, not later polish. Expose tools with narrow schemas and explicit side-effect labels. Hosts need to know which calls mutate state before they auto-approve. The 6 From Local Prototype stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion.

// 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. Enterprise-Grade Considerations Checklist

For the 7 Enterprise-Grade Considerations Checklist stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Record timings and token or query cost next to functional results. Cost visibility early prevents surprise bills when the path moves from demo to shared environments. Authenticate at the gateway and re-authorize at the data plane. A bearer token alone is not a tenancy boundary.

8. Where This Shows Up in Real Enterprise Use Cases

For the 8 Where This Shows stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph. Authenticate at the gateway and re-authorize at the data plane. A bearer token alone is not a tenancy boundary.

9. Common Pitfalls Beginners Run Into

For the 9 Common Pitfalls Beginners stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Document the happy path and the recovery path together. Retries, human gates, and dead-letter handling are part of the product, not later polish. Authenticate at the gateway and re-authorize at the data plane. A bearer token alone is not a tenancy boundary. For the 9 Common Pitfalls Beginners stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion.

10. Wrapping Up

When working through the 10 Wrapping Up stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Record timings and token or query cost next to functional results. Cost visibility early prevents surprise bills when the path moves from demo to shared environments. Log tool name, args hash, latency, and outcome for every call. Debugging agent loops without that trail wastes hours.

Operational checklist

For the Operational checklist stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state.

Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline.

Authenticate at the gateway and re-authorize at the data plane. A bearer token alone is not a tenancy boundary.

Write a short runbook: how to rotate keys, how to drain the queue, how to roll back the last ingest.

Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion.

Authenticate at the gateway and re-authorize at the data plane. A bearer token alone is not a tenancy boundary.

Before promoting the stack, freeze versions, capture a golden transcript for the critical path, and confirm rollback steps. Shared environments need rate limits, tenancy checks, and a clear owner for secret rotation. Prefer boring reliability over clever one-off demos.

Batch note for 100916d5ed60: keep provider keys out of the repo, set a per-session token ceiling, and store transcripts next to the eval fixtures so later model swaps stay comparable.