Build the MCP + A2A agent protocol stack from scratch

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

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./build",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*"]
}

// src/index.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import express from "express";
import { z } from "zod";
 
// Mock order database
const orders: Record<string, {
  id: string;
  customer: string;
  status: string;
  total: number;
  items: { name: string; price: number; qty: number }[];
  createdAt: string;
}> = {
  "ORD-1001": {
    id: "ORD-1001",
    customer: "alice@example.com",
    status: "delivered",
    total: 149.97,
    items: [
      { name: "Wireless Headphones", price: 79.99, qty: 1 },
      { name: "USB-C Cable", price: 14.99, qty: 2 },
      { name: "Phone Case", price: 39.99, qty: 1 },
    ],
    createdAt: "2026-03-15T10:30:00Z",
  },
  "ORD-1002": {
    id: "ORD-1002",
    customer: "bob@example.com",
    status: "shipped",
    total: 299.99,
    items: [{ name: "Mechanical Keyboard", price: 299.99, qty: 1 }],
    createdAt: "2026-03-28T14:15:00Z",
  },
};
 
// Create the MCP server
const server = new McpServer({
  name: "order-service",
  version: "1.0.0",
});
 
// Tool 1: Look up an order by ID
server.tool(
  "lookup-order",
  "Look up an order by its order ID. Returns order details including status, items, and total.",
  { orderId: z.string().describe("The order ID, e.g. ORD-1001") },
  async ({ orderId }) => {
    const order = orders[orderId.toUpperCase()];
    if (!order) {
      return {
        content: [{ type: "text", text: `No order found with ID: ${orderId}` }],
      };
    }
    return {
      content: [{ type: "text", text: JSON.stringify(order, null, 2) }],
    };
  }
);
 
// Tool 2: Check order status
server.tool(
  "check-order-status",
  "Check the current status of an order. Returns the status and estimated delivery.",
  { orderId: z.string().describe("The order ID to check") },
  async ({ orderId }) => {
    const order = orders[orderId.toUpperCase()];
    if (!order) {
      return {
        isError: true,
        content: [{ type: "text", text: `Order ${orderId} not found` }],
      };
    }
    const estimates: Record<string, string> = {
      pending: "3-5 business days",
      shipped: "1-2 business days",
      delivered: "Already delivered",
    };
    return {
      content: [{
        type: "text",
        text: JSON.stringify({
          orderId: order.id,
          status: order.status,
          estimatedDelivery: estimates[order.status] || "Unknown",
        }, null, 2),
      }],
    };
  }
);
 
// Tool 3: Calculate refund
server.tool(
  "calculate-refund",
  "Calculate the refund amount for returned items from an order.",
  {
    orderId: z.string().describe("The order ID"),
    itemNames: z.array(z.string()).describe("Names of items being returned"),
  },
  async ({ orderId, itemNames }) => {
    const order = orders[orderId.toUpperCase()];
    if (!order) {
      return {
        isError: true,
        content: [{ type: "text", text: `Order ${orderId} not found` }],
      };
    }
    const returnItems = order.items.filter((item) =>
      itemNames.some((name) =>
        item.name.toLowerCase().includes(name.toLowerCase())
      )
    );
    const refundAmount = returnItems.reduce(
      (sum, item) => sum + item.price * item.qty, 0
    );
    return {
      content: [{
        type: "text",
        text: JSON.stringify({
          orderId: order.id,
          returnedItems: returnItems,
          refundAmount: refundAmount.toFixed(2),
          originalTotal: order.total.toFixed(2),
        }, null, 2),
      }],
    };
  }
);
 
// Set up Streamable HTTP transport with Express
const app = express();
app.use(express.json());
 
app.post("/mcp", async (req, res) => {
  const transport = new StreamableHTTPServerTransport({
    sessionIdGenerator: undefined, // stateless mode
  });
  res.on("close", () => transport.close());
  await server.connect(transport);
  await transport.handleRequest(req, res, req.body);
});
 
app.get("/health", (_req, res) => {
  res.json({ status: "ok", server: "order-service", tools: 3 });
});
 
app.listen(3050, () => {
  console.error("MCP order-service running on http://localhost:3050");
  console.error("MCP endpoint: POST http://localhost:3050/mcp");
});

npx tsc && node build/index.js

# server.py
from mcp.server.fastmcp import FastMCP
 
mcp = FastMCP("order-service")
 
# Mock data
ORDERS = {
    "ORD-1001": {
        "id": "ORD-1001",
        "customer": "alice@example.com",
        "status": "delivered",
        "total": 149.97,
        "items": [
            {"name": "Wireless Headphones", "price": 79.99, "qty": 1},
            {"name": "USB-C Cable", "price": 14.99, "qty": 2},
            {"name": "Phone Case", "price": 39.99, "qty": 1},
        ],
        "createdAt": "2026-03-15T10:30:00Z",
    },
    "ORD-1002": {
        "id": "ORD-1002",
        "customer": "bob@example.com",
        "status": "shipped",
        "total": 299.99,
        "items": [{"name": "Mechanical Keyboard", "price": 299.99, "qty": 1}],
        "createdAt": "2026-03-28T14:15:00Z",
    },
}
 
 
@mcp.tool()
def lookup_order(order_id: str) -> str:
    """Look up an order by its order ID.
 
    Args:
        order_id: The order ID, e.g. ORD-1001
    """
    import json
    order = ORDERS.get(order_id.upper())
    if not order:
        return f"No order found with ID: {order_id}"
    return json.dumps(order, indent=2)
 
 
@mcp.tool()
def check_order_status(order_id: str) -> str:
    """Check the current status and estimated delivery for an order.
 
    Args:
        order_id: The order ID to check
    """
    import json
    order = ORDERS.get(order_id.upper())
    if not order:
        return f"Order {order_id} not found"
    estimates = {
        "pending": "3-5 business days",
        "shipped": "1-2 business days",
        "delivered": "Already delivered",
    }
    return json.dumps({
        "orderId": order["id"],
        "status": order["status"],
        "estimatedDelivery": estimates.get(order["status"], "Unknown"),
    }, indent=2)
 
 
@mcp.tool()
def calculate_refund(order_id: str, item_names: list[str]) -> str:
    """Calculate the refund amount for returned items from an order.
 
    Args:
        order_id: The order ID
        item_names: Names of items being returned
    """
    import json
    order = ORDERS.get(order_id.upper())
    if not order:
        return f"Order {order_id} not found"
    returned = [
        item for item in order["items"]
        if any(name.lower() in item["name"].lower() for name in item_names)
    ]
    refund = sum(item["price"] * item["qty"] for item in returned)
    return json.dumps({
        "orderId": order["id"],
        "returnedItems": returned,
        "refundAmount": f"{refund:.2f}",
        "originalTotal": f"{order['total']:.2f}",
    }, indent=2)
 
 
if __name__ == "__main__":
    mcp.run(transport="streamable-http", host="0.0.0.0", port=3050)

npx @modelcontextprotocol/inspector --url http://localhost:3050/mcp

{
  "name": "Customer Support Agent",
  "description": "Handles order inquiries, status checks, and refund calculations",
  "version": "1.0.0",
  "capabilities": {
    "streaming": false,
    "pushNotifications": false
  },
  "defaultInputModes": ["text"],
  "defaultOutputModes": ["text"],
  "supportedInterfaces": [
    {
      "protocolBinding": "JSONRPC",
      "url": "http://localhost:4000"
    }
  ],
  "skills": [
    {
      "id": "order-lookup",
      "name": "Order Lookup",
      "description": "Look up order details, status, and calculate refunds for customer orders",
      "tags": ["orders", "support", "refunds"]
    }
  ]
}

mkdir a2a-support-agent && cd a2a-support-agent
npm init -y
npm install @a2a-js/sdk express uuid
npm install @modelcontextprotocol/sdk
npm install -D typescript @types/node @types/express @types/uuid
npx tsc --init

// src/agent.ts
import express from "express";
import { v4 as uuidv4 } from "uuid";
import {
  type AgentExecutor,
  type RequestContext,
  type ExecutionEventBus,
  DefaultRequestHandler,
  InMemoryTaskStore,
} from "@a2a-js/sdk/server";
import { type AgentCard, type Message } from "@a2a-js/sdk";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 
// Define the Agent Card
const agentCard: AgentCard = {
  name: "Customer Support Agent",
  description:
    "Handles order inquiries, status checks, and refund calculations. " +
    "Send a customer question about an order and get a detailed response.",
  version: "1.0.0",
  capabilities: { streaming: false, pushNotifications: false },
  defaultInputModes: ["text"],
  defaultOutputModes: ["text"],
  supportedInterfaces: [
    { protocolBinding: "JSONRPC", url: "http://localhost:4000" },
  ],
  skills: [
    {
      id: "order-lookup",
      name: "Order Lookup",
      description:
        "Look up order details, check status, and calculate refunds",
      tags: ["orders", "support", "refunds"],
    },
  ],
};
 
// MCP client helper: call a tool on the order service
async function callMcpTool(
  toolName: string,
  args: Record<string, unknown>
): Promise<string> {
  const transport = new StreamableHTTPClientTransport(
    new URL("http://localhost:3050/mcp")
  );
  const client = new Client(
    { name: "support-agent", version: "1.0.0" },
    { capabilities: {} }
  );
 
  try {
    await client.connect(transport);
    const result = await client.callTool({ name: toolName, arguments: args });
    const textContent = result.content.find(
      (c: { type: string }) => c.type === "text"
    );
    return textContent ? (textContent as { text: string }).text : "No result";
  } finally {
    await client.close();
  }
}
 
// Simple intent detection from the customer message
function detectIntent(message: string): {
  tool: string;
  args: Record<string, unknown>;
} | null {
  const lower = message.toLowerCase();
  // Extract order ID pattern
  const orderMatch = message.match(/ORD-\d+/i);
  const orderId = orderMatch ? orderMatch[0].toUpperCase() : null;
 
  if (!orderId) return null;
 
  if (lower.includes("refund") || lower.includes("return")) {
    // Extract item names after "return" or "refund"
    const itemMatch = lower.match(
      /(?:return|refund).*?(?:the|my)?\s+(.+?)(?:\s+from|\s+on|\s*$)/
    );
    const itemNames = itemMatch
      ? itemMatch[1].split(/,\s*| and /).map((s) => s.trim())
      : [];
    return {
      tool: "calculate-refund",
      args: { orderId, itemNames },
    };
  }
 
  if (lower.includes("status") || lower.includes("where")) {
    return { tool: "check-order-status", args: { orderId } };
  }
 
  return { tool: "lookup-order", args: { orderId } };
}
 
// The AgentExecutor processes incoming A2A tasks
class SupportAgentExecutor implements AgentExecutor {
  async execute(
    context: RequestContext,
    eventBus: ExecutionEventBus
  ): Promise<void> {
    const userMessage =
      context.message?.parts
        ?.filter((p: { kind: string }) => p.kind === "text")
        .map((p: { text: string }) => p.text)
        .join(" ") || "";
 
    console.error(`[SupportAgent] Received: "${userMessage}"`);
 
    // Detect what the customer wants and which MCP tool to call
    const intent = detectIntent(userMessage);
 
    let responseText: string;
 
    if (!intent) {
      responseText =
        "I can help with order lookups, status checks, and refund " +
        "calculations. Please include your order ID (e.g., ORD-1001).";
    } else {
      try {
        console.error(
          `[SupportAgent] Calling MCP tool: ${intent.tool}`,
          intent.args
        );
        const toolResult = await callMcpTool(intent.tool, intent.args);
        responseText =
          `Here's what I found:\n\n${toolResult}`;
      } catch (error) {
        responseText =
          `I encountered an error looking up your order. ` +
          `Please try again or contact us directly.`;
        console.error("[SupportAgent] MCP error:", error);
      }
    }
 
    // Publish the response back through A2A
    const responseMessage: Message = {
      kind: "message",
      messageId: uuidv4(),
      role: "agent",
      parts: [{ kind: "text", text: responseText }],
      contextId: context.contextId,
    };
    eventBus.publish(responseMessage);
    eventBus.finished();
  }
 
  // Required by AgentExecutor interface
  cancelTask = async (): Promise<void> => {};
}
 
// Wire it all together with an Express server
const taskStore = new InMemoryTaskStore();
const handler = new DefaultRequestHandler(
  agentCard,
  taskStore,
  new SupportAgentExecutor()
);
 
const app = express();
app.use(express.json());
 
// A2A well-known endpoint for agent discovery
app.get("/.well-known/agent.json", (_req, res) => {
  res.json(agentCard);
});
 
// A2A JSON-RPC endpoint
app.post("/", async (req, res) => {
  const result = await handler.handleRequest(req.body);
  res.json(result);
});
 
app.listen(4000, () => {
  console.error("A2A Support Agent running on http://localhost:4000");
  console.error(
    "Agent Card: http://localhost:4000/.well-known/agent.json"
  );
});

pip install "a2a-sdk[http-server]" uvicorn
pip install mcp

# agent.py
import json
import re
import uvicorn
from a2a.server.apps import A2AStarletteApplication
from a2a.server.request_handlers import DefaultRequestHandler
from a2a.server.agent_execution import AgentExecutor, RequestContext
from a2a.server.events import EventQueue
from a2a.server.tasks import InMemoryTaskStore
from a2a.types import (
    AgentCard, AgentSkill, AgentCapabilities, AgentInterface,
    Message, TextPart,
)
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client
 
 
# Agent Card definition
agent_card = AgentCard(
    name="Customer Support Agent",
    description=(
        "Handles order inquiries, status checks, and refund calculations. "
        "Send a customer question about an order and get a detailed response."
    ),
    version="1.0.0",
    capabilities=AgentCapabilities(streaming=False),
    default_input_modes=["text"],
    default_output_modes=["text"],
    supported_interfaces=[
        AgentInterface(
            protocol_binding="JSONRPC",
            url="http://localhost:4000",
        )
    ],
    skills=[
        AgentSkill(
            id="order-lookup",
            name="Order Lookup",
            description="Look up order details, check status, and calculate refunds",
            tags=["orders", "support", "refunds"],
        )
    ],
)
 
 
async def call_mcp_tool(
    tool_name: str, args: dict
) -> str:
    """Call a tool on the MCP order service."""
    async with streamablehttp_client("http://localhost:3050/mcp") as (
        read_stream, write_stream, _
    ):
        async with ClientSession(read_stream, write_stream) as session:
            await session.initialize()
            result = await session.call_tool(tool_name, arguments=args)
            for content in result.content:
                if content.type == "text":
                    return content.text
    return "No result"
 
 
def detect_intent(message: str) -> tuple[str, dict] | None:
    """Simple intent detection from customer message."""
    lower = message.lower()
    match = re.search(r"ORD-\d+", message, re.IGNORECASE)
    if not match:
        return None
    order_id = match.group(0).upper()
 
    if "refund" in lower or "return" in lower:
        item_match = re.search(
            r"(?:return|refund).*?(?:the|my)?\s+(.+?)(?:\s+from|\s+on|\s*$)",
            lower,
        )
        item_names = (
            [s.strip() for s in re.split(r",\s*| and ", item_match.group(1))]
            if item_match
            else []
        )
        return "calculate-refund", {"orderId": order_id, "itemNames": item_names}
 
    if "status" in lower or "where" in lower:
        return "check-order-status", {"orderId": order_id}
 
    return "lookup-order", {"orderId": order_id}
 
 
class SupportAgentExecutor(AgentExecutor):
    """Processes incoming A2A tasks by calling MCP tools."""
 
    async def execute(
        self, context: RequestContext, event_queue: EventQueue
    ) -> None:
        user_text = ""
        if context.message and context.message.parts:
            user_text = " ".join(
                p.text for p in context.message.parts if hasattr(p, "text")
            )
 
        print(f'[SupportAgent] Received: "{user_text}"')
        intent = detect_intent(user_text)
 
        if not intent:
            response_text = (
                "I can help with order lookups, status checks, and refund "
                "calculations. Please include your order ID (e.g., ORD-1001)."
            )
        else:
            tool_name, args = intent
            try:
                print(f"[SupportAgent] Calling MCP tool: {tool_name}", args)
                tool_result = await call_mcp_tool(tool_name, args)
                response_text = f"Here's what I found:\n\n{tool_result}"
            except Exception as e:
                response_text = (
                    "I encountered an error looking up your order. "
                    "Please try again or contact us directly."
                )
                print(f"[SupportAgent] MCP error: {e}")
 
        await event_queue.enqueue_event(
            Message(
                role="agent",
                parts=[TextPart(text=response_text)],
            )
        )
 
 
# Wire it all up
request_handler = DefaultRequestHandler(
    agent_executor=SupportAgentExecutor(),
    task_store=InMemoryTaskStore(),
)
a2a_app = A2AStarletteApplication(
    agent_card=agent_card, http_handler=request_handler
)
 
if __name__ == "__main__":
    uvicorn.run(a2a_app.build(), host="0.0.0.0", port=4000)

// src/client.ts
 
// Step 1: Discover the agent by fetching its Agent Card
async function discoverAgent(baseUrl: string) {
  const res = await fetch(`${baseUrl}/.well-known/agent.json`);
  if (!res.ok) throw new Error(`Agent discovery failed: ${res.status}`);
  const card = await res.json();
  console.log(`Discovered agent: ${card.name}`);
  console.log(`Skills: ${card.skills.map((s: { name: string }) => s.name).join(", ")}`);
  return card;
}
 
// Step 2: Send a task using A2A's JSON-RPC format
async function sendTask(agentUrl: string, message: string) {
  const requestBody = {
    jsonrpc: "2.0",
    id: crypto.randomUUID(),
    method: "message/send",
    params: {
      message: {
        role: "user",
        parts: [{ kind: "text", text: message }],
      },
    },
  };
 
  const res = await fetch(agentUrl, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(requestBody),
  });
 
  const response = await res.json();
 
  if (response.error) {
    throw new Error(`A2A error: ${response.error.message}`);
  }
 
  return response.result;
}
 
// Run the client
async function main() {
  const agentUrl = "http://localhost:4000";
 
  // Discover
  const card = await discoverAgent(agentUrl);
 
  // Send tasks
  const queries = [
    "What's the status of order ORD-1002?",
    "I'd like to return the Wireless Headphones from ORD-1001",
    "Can you look up order ORD-1001?",
  ];
 
  for (const query of queries) {
    console.log(`\n--- Sending: "${query}" ---`);
    const result = await sendTask(agentUrl, query);
 
    // Extract the agent's text response
    if (result.message) {
      const text = result.message.parts
        .filter((p: { kind: string }) => p.kind === "text")
        .map((p: { text: string }) => p.text)
        .join("\n");
      console.log("Response:", text);
    }
  }
}
 
main().catch(console.error);

# client.py
import asyncio
import json
import uuid
import httpx
 
 
async def discover_agent(base_url: str) -> dict:
    """Fetch the agent's Agent Card."""
    async with httpx.AsyncClient() as client:
        res = await client.get(f"{base_url}/.well-known/agent.json")
        res.raise_for_status()
        card = res.json()
        print(f"Discovered agent: {card['name']}")
        skills = ", ".join(s["name"] for s in card["skills"])
        print(f"Skills: {skills}")
        return card
 
 
async def send_task(agent_url: str, message: str) -> dict:
    """Send a task to an A2A agent using JSON-RPC."""
    request_body = {
        "jsonrpc": "2.0",
        "id": str(uuid.uuid4()),
        "method": "message/send",
        "params": {
            "message": {
                "role": "user",
                "parts": [{"kind": "text", "text": message}],
            },
        },
    }
    async with httpx.AsyncClient() as client:
        res = await client.post(
            agent_url,
            json=request_body,
            headers={"Content-Type": "application/json"},
        )
        response = res.json()
        if "error" in response:
            raise RuntimeError(f"A2A error: {response['error']['message']}")
        return response["result"]
 
 
async def main():
    agent_url = "http://localhost:4000"
 
    # Discover
    await discover_agent(agent_url)
 
    # Send tasks
    queries = [
        "What's the status of order ORD-1002?",
        "I'd like to return the Wireless Headphones from ORD-1001",
        "Can you look up order ORD-1001?",
    ]
 
    for query in queries:
        print(f'\n--- Sending: "{query}" ---')
        result = await send_task(agent_url, query)
 
        if "message" in result:
            text = "\n".join(
                p["text"]
                for p in result["message"]["parts"]
                if p.get("kind") == "text"
            )
            print("Response:", text)
 
 
asyncio.run(main())

# Terminal 1: MCP order server (from Part 1)
cd mcp-order-server && node build/index.js
 
# Terminal 2: A2A support agent (from Part 2)
cd a2a-support-agent && npx tsc && node build/agent.js
 
# Terminal 3: A2A client
cd a2a-support-agent && npx tsc && node build/client.js

// Add to your MCP server's Express setup
function requireAuth(
  req: express.Request,
  res: express.Response,
  next: express.NextFunction
) {
  const authHeader = req.headers.authorization;
  if (!authHeader?.startsWith("Bearer ")) {
    res.status(401).json({ error: "Missing bearer token" });
    return;
  }
  const token = authHeader.slice(7);
  // In production: validate JWT against your auth provider's JWKS
  // const payload = await jwtVerify(token, JWKS);
  next();
}
 
app.post("/mcp", requireAuth, async (req, res) => {
  // ... existing handler
});

{
  "name": "Customer Support Agent",
  "supportedInterfaces": [
    { "protocolBinding": "JSONRPC", "url": "http://localhost:4000" }
  ],
  "securitySchemes": {
    "bearer": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }
  },
  "security": [{ "bearer": [] }]
}

// Streaming A2A client
async function sendStreamingTask(agentUrl: string, message: string) {
  const requestBody = {
    jsonrpc: "2.0",
    id: crypto.randomUUID(),
    method: "message/stream",
    params: {
      message: {
        role: "user",
        parts: [{ kind: "text", text: message }],
      },
    },
  };
 
  const res = await fetch(agentUrl, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Accept: "text/event-stream",
    },
    body: JSON.stringify(requestBody),
  });
 
  // Read the SSE stream
  const reader = res.body?.getReader();
  const decoder = new TextDecoder();
 
  while (reader) {
    const { done, value } = await reader.read();
    if (done) break;
 
    const chunk = decoder.decode(value);
    const lines = chunk.split("\n").filter((l) => l.startsWith("data: "));
 
    for (const line of lines) {
      const event = JSON.parse(line.slice(6));
 
      switch (event.kind) {
        case "status-update":
          console.log(`Status: ${event.status.state}`);
          break;
        case "artifact-update":
          console.log("Received artifact:", event.artifact);
          break;
        case "message":
          const text = event.message.parts
            .filter((p: { kind: string }) => p.kind === "text")
            .map((p: { text: string }) => p.text)
            .join("\n");
          console.log("Agent:", text);
          break;
      }
    }
  }
}