Building a Server: Tools, Resources & Prompts

# server.py — official 'mcp' Python package, FastMCP style
import os

import httpx
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("orders-server")

API_BASE = "https://api.example.internal"
API_KEY = os.environ["ORDERS_API_KEY"]     # server-side; model never sees it


@mcp.tool()
def search_orders(query: str, status: str = "open", limit: int = 10) -> str:
    """Search customer orders by free-text query and status.

    Returns up to 'limit' order summaries (id, customer, status, total).
    Use for questions about order history or finding a specific order.
    Do NOT use for refunds or edits -- this tool is read-only.
    """
    resp = httpx.get(
        f"{API_BASE}/orders",
        params={"q": query, "status": status, "limit": limit},
        headers={"Authorization": f"Bearer {API_KEY}"},
        timeout=10.0,
    )
    if resp.status_code == 401:
        return ("Error: orders API rejected credentials. The server's "
                "ORDERS_API_KEY is missing or expired -- tell the user "
                "to check server configuration. Do not retry.")
    resp.raise_for_status()
    orders = resp.json()["orders"]
    lines = [f"{o['id']} | {o['customer']} | {o['status']} | {o['total']}"
             for o in orders]
    return "\n".join(lines) if lines else "No orders matched."


if __name__ == "__main__":
    mcp.run()        # stdio transport by default

@mcp.resource("orders://status-codes")
def status_codes() -> str:
    """Reference: every order status code and its meaning."""
    return ("open: placed, not yet shipped\n"
            "shipped: with carrier\n"
            "cancelled: cancelled before shipment")


@mcp.resource("orders://recent/{customer_id}")
def recent_orders(customer_id: str) -> str:
    """The 5 most recent orders for one customer, as a summary."""
    return fetch_recent(customer_id)     # your API call


@mcp.prompt()
def order_investigation(order_id: str) -> str:
    """Template for investigating a problematic order end to end."""
    return (f"Investigate order {order_id}. Steps: (1) fetch the order "
            f"and its status history; (2) check shipping events; "
            f"(3) summarize what went wrong and draft a customer reply. "
            f"Cite specific timestamps.")