This is part 4 of 9 in the AI-Native Engineering series. Start with the course index or continue to the next part below.
Audience. You should know one programming language, Git, a shell, HTTP, and how to run tests. The examples use plain files, JSON, HTTP, Git, and shell so the ideas transfer across agent SDKs.
Shared capstone. Every part extends the same shop-agent: a support agent that searches products, inspects orders, and prepares—but never executes—a refund recommendation. The companion repository lives alongside the site source.
Connect Capabilities Through MCP Portals
Capability. Expose tools through a governed Model Context Protocol (MCP) endpoint without creating a credential and audit mess.
MCP standardizes how a host discovers and invokes tools, resources, and prompts. The official specification separates the host/client from servers and requires explicit authorization boundaries. The official Registry is a discovery catalog; an enterprise portal or gateway is the controlled front door.
Portal mental model.
flowchart LR
A[Agent host] -->|authenticates once| P[MCP portal / gateway]
P -->|filters and audits| C[Catalogue]
P -->|routes| O1[Orders server]
P -->|routes| O2[Products server]
P -->|adapts| O3[Internal API adapter]
P -.->|deny / redact / rate-limit| D[Blocked call]A portal solves discovery, authentication, authorization, routing, and observability in one place. It does not make an unsafe upstream server safe by magic.
Text equivalent: The agent authenticates to one portal. The portal filters the catalogue, checks scopes, audits the call, and routes it to an approved orders, products, or internal API server. A denied call is blocked, redacted, or rate-limited before it reaches an upstream server.
Tool contract. Every tool needs a stable name, purpose, JSON Schema arguments, typed result, error shape, timeout, idempotency behavior, required scope, and an example. Say what the tool does not do. Prefer prepare_refund over refund when a human must approve the action.
Build lab. Implement a tiny MCP-like HTTP server with search_products and get_order. Put it behind a local gateway that:
- authenticates the caller;
- filters tools by scope (
orders:read,catalogue:read); - validates arguments at the boundary;
- logs caller, tool, arguments hash, result status, latency, and trace ID;
- rejects unknown tools and over-broad arguments.
Break it. Call the backend directly, use a stolen-looking token with the wrong audience, request an unlisted tool, and pass a prompt-injection string as an order note. The gateway must block or safely treat each case.
Acceptance test. A user without orders:read cannot discover or invoke get_order; every permitted call has an audit record; repeated prepare_refund calls return one recommendation record (the demo’s only write-like side effect).
Module contract. Starting state: Gateway in course/shop-agent/shop_agent.py. Add or document one typed tool; run python3 run_labs.py; prove scope denial, audit, and idempotency.
Use when / don’t use when. Use a portal when many agents or teams share tools and need central governance. A single local, low-risk prototype may use a direct server, but migrate before credentials, sensitive data, or multiple teams appear.
Continue the series
← Previous: Engineer Context, Not Just Prompts · Next: Make the Codebase Agent-Ready →
Return to the course index.