Expose your systems with MCP

// The surface the platform's agents act against: an MCP server over Streamable HTTP,
// stateless (a fresh server + transport per request, no sessions), protected
// by a bearer token that lives platform-side only as an encrypted connection.
// Same SDK and transport the demo portals use.
import { createHash, timingSafeEqual } from 'node:crypto';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
import { z } from 'zod';

/** Constant-time bearer comparison (hash first so lengths never leak). */
function tokenMatches(header, expected) {
  if (typeof header !== 'string' || !header.startsWith('Bearer ')) return false;
  const presented = createHash('sha256').update(header.slice(7)).digest();
  const wanted = createHash('sha256').update(expected).digest();
  return timingSafeEqual(presented, wanted);
}

const text = (value) => ({ content: [{ type: 'text', text: JSON.stringify(value) }] });
const toolError = (code, message) => ({
  content: [{ type: 'text', text: JSON.stringify({ error: code, message }) }],
  isError: true,
});

function buildServer(store, log) {
  const server = new McpServer({ name: 'acme-orders', version: '1.0.0' });

  server.registerTool(
    'orders.get',
    {
      description:
        'Fetch one order by id (ord_…): customer, total, currency, status and refunds so far. The order system is the source of truth.',
      inputSchema: { order_id: z.string().min(3) },
    },
    async ({ order_id }) => {
      const order = store.getOrder(order_id);
      log('orders.get', order !== null, { order_id });
      if (order === null) return toolError('NOT_FOUND', `No order matches ${order_id}`);
      return text(order);
    },
  );

  server.registerTool(
    'orders.refund',
    {
      description:
        'Refund part or all of an order. amount_minor is in minor units (fils); the refund never exceeds the remaining balance. Idempotent per idempotency_key — reuse the same key when retrying. This moves money: it is gated by a human approval on the platform.',
      inputSchema: {
        order_id: z.string().min(3),
        amount_minor: z.number().int().positive(),
        reason: z.string().min(3).max(500),
        idempotency_key: z.string().min(8).max(120),
      },
    },
    async ({ order_id, amount_minor, reason, idempotency_key }) => {
      const result = store.refund(order_id, amount_minor, reason, idempotency_key);
      log('orders.refund', result.error === undefined, { order_id, amount_minor });
      if (result.error !== undefined) return toolError(result.error, result.message);
      return text({ ok: true, ...result });
    },
  );

  return server;
}

/**
 * Express handler for `POST /mcp`. Mount after `express.json()` so the parsed
 * body can be handed to the transport.
 */
export function createMcpHandler({ bearerToken, store, log = () => {} }) {
  return async (req, res) => {
    if (!tokenMatches(req.headers.authorization, bearerToken)) {
      log('mcp.auth', false, {});
      res.status(401).json({
        jsonrpc: '2.0',
        error: { code: -32001, message: 'Unauthorized: bearer credential required.' },
        id: null,
      });
      return;
    }
    const server = buildServer(store, log);
    const transport = new StreamableHTTPServerTransport({
      sessionIdGenerator: undefined,
      enableJsonResponse: true,
    });
    res.on('close', () => {
      void transport.close();
      void server.close();
    });
    try {
      await server.connect(transport);
      await transport.handleRequest(req, res, req.body);
    } catch (error) {
      log('mcp.error', false, {
        message: error instanceof Error ? error.message : String(error),
      });
      if (!res.headersSent) {
        res.status(500).json({
          jsonrpc: '2.0',
          error: { code: -32603, message: 'Internal error' },
          id: null,
        });
      }
    }
  };
}

# pip install "mcp[cli]" uvicorn      MCP Python SDK v2 (Python 3.10+), Streamable HTTP
import hmac
import os
from typing import Annotated

from pydantic import AnyHttpUrl, Field

from mcp.server import MCPServer
from mcp.server.auth.provider import AccessToken, TokenVerifier
from mcp.server.auth.settings import AuthSettings
from mcp.server.transport_security import TransportSecuritySettings
from mcp.types import ToolAnnotations

PUBLIC_MCP_URL = os.environ["PUBLIC_MCP_URL"]      # https://api.acme.example/mcp
SERVICE_TOKEN = os.environ["MCP_BEARER_TOKEN"]     # what the platform-side connection holds


class ServiceTokenVerifier(TokenVerifier):
    """The platform presents the connection credential as Authorization: Bearer <token>."""

    async def verify_token(self, token: str) -> AccessToken | None:
        if hmac.compare_digest(token, SERVICE_TOKEN):
            return AccessToken(token=token, client_id="hive", scopes=["orders"])
        return None


mcp = MCPServer(
    "acme-orders",
    token_verifier=ServiceTokenVerifier(),
    auth=AuthSettings(
        issuer_url=AnyHttpUrl("https://auth.acme.example"),   # advertised in RFC 9728 metadata
        resource_server_url=AnyHttpUrl(PUBLIC_MCP_URL),
        required_scopes=["orders"],
    ),
)

ORDERS = {"ord_1001": {"id": "ord_1001", "status": "delivered", "total_minor": 12900, "refunds": []}}


@mcp.tool(name="orders.get", annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False))
def orders_get(order_id: Annotated[str, Field(min_length=3)]) -> dict:
    """Fetch one order by id (ord_…): status, total in minor units and refunds so far."""
    order = ORDERS.get(order_id)
    if order is None:
        return {"error": "NOT_FOUND", "message": f"No order matches {order_id}"}
    return order


@mcp.tool(name="orders.refund", annotations=ToolAnnotations(destructive_hint=True, idempotent_hint=True))
def orders_refund(order_id: str, amount_minor: Annotated[int, Field(gt=0)], reason: str,
                  idempotency_key: Annotated[str, Field(min_length=8)]) -> dict:
    """Refund part of an order. Idempotent per idempotency_key. Gated by a human approval on the platform."""
    order = ORDERS.get(order_id)
    if order is None:
        return {"error": "NOT_FOUND", "message": f"No order matches {order_id}"}
    for r in order["refunds"]:
        if r["idempotency_key"] == idempotency_key:
            return {"ok": True, "refund": r, "replayed": True}
    refunded = sum(r["amount_minor"] for r in order["refunds"])
    if refunded + amount_minor > order["total_minor"]:
        return {"error": "AMOUNT_EXCEEDS_BALANCE", "message": f"Refundable balance is {order['total_minor'] - refunded}"}
    refund = {"id": f"rf_{len(order['refunds']) + 1}", "amount_minor": amount_minor,
              "reason": reason, "idempotency_key": idempotency_key}
    order["refunds"].append(refund)
    return {"ok": True, "refund": refund, "replayed": False}


# A Starlette ASGI app with the endpoint at /mcp. stateless_http: a fresh transport per
# request (no sessions to hijack); json_response: plain JSON replies. Behind a real
# hostname the transport answers 421 until that host is allow-listed.
app = mcp.streamable_http_app(
    stateless_http=True,
    json_response=True,
    transport_security=TransportSecuritySettings(allowed_hosts=["api.acme.example", "api.acme.example:*"]),
)
# uvicorn server:app --port 4100   → register {PUBLIC_MCP_URL} on the platform with auth_kind "bearer"